minlopro-dx

About

This is a blueprint repository for typical Salesforce org-based project which is accompanied with CI/CD automations.

Prerequisites

Install node version specified in package.json file. It's recommended to use NVM in order to manage NODE versions on local machine.

Download and install OpenJDK (11<). This step is mandatory for prettier-plugin-apex to work as expected. Refer to this link for configuring $JAVA_HOME environment variable.

Additionally install jq utility.

Run bash ./scripts/deploy/build.sh in order to load project dependencies.

Look through the pre-configured GitHub Workflows/Actions located in .github/workflows/ folder.

Familiarise yourself with Salesforce environments involved and automations built around them:

Spin up scratch org by running Create Scratch Org GitHub Action Workflow.

Authorize scratch org using authorize_org.sh command.

Make sure that the changed codebase files are prettified via npm run prettier:src:write command. Alternatively, you can run npm run prettier:src:check in order to identify non-prettified files.

Branches

main

Comprises all source code in the repository.

release/**

Short-living branch which comprises features to be deployed to Production org. Descendant of main branch.

develop

When the features are finished then they are merged into develop. Descendant of main branch.

For visual context, take a look at flowchart below:

Release Branch Preparation

Lead developer is responsible for preparing release branches. These branches, named release/**, serve as buffers for the upcoming release and are created from the main branch.

Follow the steps below:

1. Create release/** branch off of main.
2. Collect merged pull requests from develop branch and cherry-pick them into release/** branch. For each merge commit, you can utilize git cherry-pick -m 1 $COMMIT_SHA command.
3. Automated workflow would run quick validation against release/** branch.
4. Introduce bugfixes (if applicable).
5. Once the release/** branch is ready & validated, invoke Release workflow manually. Make sure that Do Quick Deploy? checkbox is selected!
6. The last step is to merge release/** branch into main and develop branches.

This process ensures a structured flow of features into releases, maintaining stability and predictability in release management.

Useful Commands

Deploy Codebase

npm run sf:manifest:create && npm run src:deploy:full

Publish Community

sf community publish --name "DigEx" --target-org $SCRATCH_ORG_ALIAS

Managing Environment Variables

Environment variables are useful for deploying metadata components with secrets or org-specific settings (e.g. usernames, URLs, connected app credentials). This project benefits from GitHub Secrets & Environment Variables feature. At the same time, there are project-level rules enforced with regards to using/replacing variables.

Follow steps below if there is a need to replace specific setting with variable value:

1. Define variable in GitHub repository for the given GitHub Environment(s)
2. Incorporate environment variable into .env.manifest file and provide description
3. Declare variable in affected workflow files (see .github/workflows folder)
4. Create replacement configuration in sfdx-project.json file
5. Create reference(s) in metadata components (classes, named credentials etc.) using @VAR_NAME format

As an example, refer to namedCredentials or customMetadata folders.

Scripts in package.json

Scripts that start with sf:... or src:... can be invoked with extra parameters passed to them. E.g. you can execute particular script passing in ORG alias:

// Push source to target org
npm run src:push -- -o $SCRATCH_ORG_ALIAS

Please, refer to SF CLI for more information.