join-sf-packages
v1.2.0
Published
Une los package.xml de Salesforce de una carpeta en un único deploy.xml y genera sus pre/post destructive.
Maintainers
Readme
Join .xml files (join-sf-packages)
Sobre el proyecto
Proyecto interno que genera el package para el despliegue incluidos los destructive.
Lenguajes usados
Para empezar
Instalar
Requiere Windows (x64) y Node.js con npm. Desde una consola:
npm install -g join-sf-packagesPara comprobar la instalación:
join-sf-packages --versionHasta la versión 1.1.0 el comando se llamaba
jxmlf. Si tenías instalado el paquete antiguojxmlf, desinstálalo connpm uninstall -g jxmlf.
Antes de empezar
Se aconseja adherirse a la estructura de packages aquí planteada. No obstante, también funciona con otro tipo de arquitectura, lo único que nunca debe ser diferente es la estructura de carpetas de dentro del destructive. La arquitectura aconsejada se representa a continuación:
force-app
├──...
manifest
└── <EPIC NAME>
└── feature
└── <CURRENT ENVIRONMENT>
├── .placeholder
├── example1.xml
├── example2.xml
├── example3.xml
├── example4.xml
└── destructive
├── pre
│ ├── example1.xml
│ ├── example2.xml
│ └── example3.xml
└── post
├── example4.xml
└── example5.xmlLa carpeta destructive, en caso de que haya, debe tener dos carpetas: pre y post. Cada carpeta contendrá los packages con la información que ha de ser eliminada de los entornos. A continuación se muestra un diagrama de la estructura:
destructive
├── pre
│ ├── example1.xml
│ ├── example2.xml
│ └── example3.xml
└── post
├── example4.xml
└── example5.xmlSi no se incluye la carpeta del destructive o no tiene la estructura interna de carpetas el sistema la omitirá
Uso
El uso es simple, desde un terminal escribir el comando:
join-sf-packages --p <RUTA CARPETA PACKAGES A DESPLEGAR> [--d <RUTA CARPETA DESTRUCTIVE>] --o <RUTA CARPETA DONDE SE GENERAN LOS FICHEROS>Ejemplo:
join-sf-packages --p ./manifest/tarjetas-catalogos/feature/dev --d ./manifest/tarjetas-catalogos/destructive --o ./manifest/tarjetas-catalogos/deploy/pro| Parámetro | Alias | Obligatorio | Descripción |
|-----------|-------|-------------|-------------|
| --p | -p, --packages | Sí | Carpeta con los packages (.xml) a desplegar. Solo se leen los ficheros de esa carpeta, no los de sus subcarpetas. |
| --d | -d, --destructive | No | Carpeta destructive con las subcarpetas pre y post. Por defecto <--p>/destructive. |
| --o | -o, --output | Sí | Carpeta donde se genera la salida. Si no existe, se crea. |
| --version | -V | No | Muestra la versión instalada. |
Una vez ejecutado el comando se creará en la dirección de salida (parámetro --o) una carpeta con la fecha actual seguida del número de versión (si has generado más durante el día los irá versionando):
<--o>
└── 20261112_1
├── deploy.xml
└── destructive
├── pre
│ └── pre-destructive.xml
└── post
└── post-destructive.xmlComportamiento:
- Los componentes repetidos entre packages se incluyen una sola vez y se ordenan alfabéticamente (tipos y miembros).
- Se usa la versión de API más alta de los packages unidos (
62.0si ninguno la indica). deploy.xmlse genera siempre, aunque solo haya destructive, porque Salesforce exige un manifiesto junto a los destructive.- Si un
.xmlestá mal formado o no es unpackage.xml, la herramienta se detiene con un mensaje de error y no genera nada.
Para desplegar con la CLI de Salesforce:
sf project deploy start --manifest <SALIDA>/deploy.xml --pre-destructive-changes <SALIDA>/destructive/pre/pre-destructive.xml --post-destructive-changes <SALIDA>/destructive/post/post-destructive.xmlSi no se incluye el parámetro --d el sistema buscará la carpeta "destructive" en la ruta de la carpeta de los packages (parámetro --p)
Como colaborar
Para colaborar en el proyecto es recomendable leer los requisitos y pedir acceso al equipo de sistemas.
Requisitos
Lo primero que se necesita es un IDE. Para Python es bastante recomendable usar alguno de los siguientes:
- PyCharm
- Visual Studio Code con la extensión de Python
El proyecto se gestiona con uv de Astral, que se encarga de instalar Python, el entorno virtual y las dependencias. Para instalarlo en Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"No hace falta instalar Python a mano: uv descarga la versión indicada en .python-version. Las dependencias de desarrollo están en pyproject.toml (grupo dev):
- pytest: tests
- ruff: linter y formateador
- pyinstaller: genera
join-sf-packages.exe
Estructura del proyecto
join-sf-packages
├── pyproject.toml # Metadatos, dependencias y configuración de herramientas
├── uv.lock # Versiones exactas de las dependencias (se sube al repositorio)
├── .python-version # Versión de Python que usa uv
├── package.json # Paquete npm que distribuye bin/join-sf-packages.exe
├── bin
│ └── join-sf-packages.exe # Ejecutable publicado en npm
├── scripts
│ └── check-version.mjs # Comprueba antes de publicar que el .exe tiene la versión de package.json
├── src
│ └── join_sf_packages
│ ├── __main__.py # Permite `python -m join_sf_packages` y es la entrada de PyInstaller
│ ├── cli.py # Parámetros de la línea de comandos
│ ├── builder.py # Carpeta versionada, deploy.xml y destructive
│ ├── manifest.py # Lectura, unión y escritura de package.xml
│ └── errors.py # Errores controlados
└── tests # Tests con pytestEntorno de desarrollo
uv sync # Crea .venv e instala dependencias
uv run join-sf-packages --p <RUTA> --o <RUTA> # Ejecuta la herramienta desde el código
uv run pytest # Tests
uv run ruff check . # Linter
uv run ruff format . # FormateoGenerar el ejecutable y publicar
- Subir la versión en
pyproject.toml(uv version --bump minoropatch) y poner la misma enpackage.json. - Generar el ejecutable y copiarlo a
bin/:uv run pyinstaller --onefile --name join-sf-packages --copy-metadata join-sf-packages --distpath dist --workpath build --specpath build src/join_sf_packages/__main__.py copy dist\join-sf-packages.exe bin\join-sf-packages.exe - Comprobar que
bin\join-sf-packages.exe --versionmuestra la versión nueva. - Revisar qué se va a subir:
npm pack --dry-run(solo deben aparecerpackage.json,README.mdybin/join-sf-packages.exe). - Publicar en npm (requiere
npm logincon una cuenta mantenedora del paquete):npm publish. Antes de subir,prepublishOnlycomprueba que el.exetiene la versión depackage.json.
Extensiones
A continuación se detallan algunas extensiones útiles para PyCharm:
Cuantas más extensiones, más lento se iniciará el IDE
