Information for: DEVELOPERS   PARTNERS

Development workflow with Acquia BLT

This page contains information about how you can contribute code to an Acquia BLT project.

Git workflow

Do not push direct changes to the build-artifact repository. The process of syncing the repositories is managed transparently in the background.

Recommended Git workflows to consider, depending on your team’s size, include the following options:

  • Feature branch workflow
  • Gitflow
  • Gitflow (abridged)

Feature branch workflow

The Feature branch workflow encourages all feature development work to take place on a dedicated branch, instead of committing locally to the standard master branch.

Workflows of this type have the following attributes:

  • A developer creates a new branch based on an up-to-date master branch to start work on a new feature.
  • When the developer completes the work, they push the feature branch to origin (or whatever name the developer gave the remote of their forked repository).
  • The developer opens a pull request against the master branch, giving other team members the chance to review the work completed before merging into master.
  • After the work is accepted, the developer merges the work into the master branch.

The preceding flow is best-suited for a small team. For larger teams, consider using the Gitflow workflow.

Gitflow workflow

The Gitflow workflow builds on the concept of the feature branch workflow. Developers commit to feature branches instead of directly to master, and they will submit pull requests against a develop branch serving as an integration branch for new features.

The Gitflow specifics are as follows:

  • A developer creates a new branch based on an up-to-date develop branch to start work on a new feature.
  • When the developer completes the work, they push the feature branch to origin.
  • The developer opens a pull request against the develop branch, giving other team members the chance to review the work completed before merging into develop.
  • After the developer merges the feature group into the develop branch, or as a pre-determined release date approaches, the developer creates a new release branch off of develop.
  • From then on, the team or release master works the release branch to add only what is necessary for the release, while the rest of the team continues feature development against the develop branch.
  • The release master merges the release branch into master, and rebases develop onto master upon merging.

Gitflow workflow allows a larger team to work off an integrated branch (develop), while maintaining a stable master branch remaining in a good state.

Gitflow workflow (abridged version)

The Gitflow workflow builds on the concept of the feature branch workflow. Developers commit to feature branches instead of directly to master, and they will submit pull requests against a develop branch, serving as an integration branch for new features. The Gitflow workflow (abridged) specifics are as follows:

  • A developer creates a new branch based on an up-to-date develop branch to start work on a new feature.
  • When the developer completes the work, they push the feature branch to origin.
  • The developer opens a pull request against the develop branch, giving other team members the chance to review the work completed before merging into develop.
  • After merging the feature group into the develop branch, and determining the branch is in a good state, the developer merges into the master branch.

The Gitflow workflow (abridged) still allows a team to work off an integrated branch (develop), while maintaining a stable master branch, but removes the release branch component of the flow.

Note

In all preceding workflows, a developer or team merges hotfixes directly into a hotfix branch they can merge to master.

Workflow example: Local development

  1. Assign an issue to yourself in your issue tracking system (in this example, Atlassian JIRA).

  2. Fetch upstream to ensure you are working with the most current code:

    git fetch upstream
    
  3. Create a new local feature branch (named according to the pattern abc-123-short-desc, where ABC is the JIRA prefix of your JIRA project and 123 is the ticket number for the work), and then run the following command:

    git checkout -b abc-123-short-desc upstream/master
    
  4. Reset your local environment (if necessary) to a clean state by running one of the following commands:

    • blt setup
      
    • blt sync
      
  5. Make your code changes.

  6. Commit your changes to the repository. Each commit must be logically atomic, and your commit messages should use a pattern similar to ABC-123 A grammatically correct sentence ending within punctuation.

  7. Run tests and validation scripts with the following commands:

    blt validate
    blt tests
    
  8. Ensure you make no added changes to the upstream repository by running the following command:

    git fetch upstream
    

    If necessary, rebase by running the following command:

    git rebase upstream/master
    
  9. Push your work to your forked repository (origin) by running the following command:

    git push --set-upstream origin abc-123-short-desc
    
  10. Create a pull request.

Creating a pull request

Pull requests must never contain merge commits from upstream changes. To avoid merge commits from upstream changes, use the git rebase command instead of pulling and merging.

Push your feature branch to your fork of the upstream repository, and then submit a pull request from your-fork/feature-branch to canonical-repo/develop. You may optionally use Hub to submit your pull request from the command line with the following command:

hub pull-request

To enforce consistency on a project, you can configure a pull request template by running the following command:

git config --global --add hub.pull-request-template-path ~/.pr-template

Resolving merge conflicts

Merge conflicts result when several developers submit pull requests that change the same code, and Git cannot resolve the conflict. If two developers add update hooks to the same module at the same time, the changes conflict because you must number update hooks in a defined sequence.

Developers are responsible for fixing merge conflicts on their own pull requests.

Use the following process to resolve a merge conflict:

  1. Fetch upstream history by running the following command:

    git fetch upstream
    
  2. Check out the branch based on your open pull request such as master, and run the following command:

    git checkout master
    
  3. Ensure your branch matches upstream by running the following command:

    git reset --hard upstream/master
    
  4. Check out your feature branch by running the following command:

    git checkout feature/foo
    
  5. Merge master by running the following command:

    git merge master
    

    Git will display a message that indicates the existence of a merge conflict.

  6. Run the following command to find any conflicting files:

    git status
    
  7. Edit the files to resolve the conflict.

  8. Add all files that you have fixed by running the following command:

    git add
    
  9. Run the following command to finish the merge:

    git commit
    
  10. Complete the process by updating the pull request with the following command:

    git push origin feature/foo
    

Integration (merging pull requests)

Acquia recommends the use of the either the integration manager or the peer review models of the integration workflow.

Note

In the integration manager or peer review workflow, no one must ever commit their own code to the primary working branch.

Integration manager

The integration manager model requires one (or more) lead developers to take responsibility for merging all pull requests. Integration management ensures consistency in quality control and identifies any potential issues with related, open pull requests.

A small group is selected to be integrators who review all commits. If an integrator performs work, fellow integrators must review all work as if they were a developer.

Peer review

The peer review model removes the bottleneck of designated integrators, but still eliminates commits directly to the working branch. A different developer than the developer that submitted the original commit reviews every commit.

Continuous integration

After a developer submits or merges a pull request, Acquia’s continuous integration (CI) solution builds a website artifact, installs an ephemeral instance of Drupal, and runs tests against them.

For more information about the build process, see Continuous integration.

Deploying code on Acquia Cloud

After work is merged on GitHub and tested though the continuous integration solution, a separate production-ready built artifact is built and deployed to Acquia Cloud. The building and deployment can be done either manually or by using automation.

For more information, see Deployment workflow.

Release process

A designated Release Master will perform the release to production. The release master is typically the project’s technical architect.

For detailed information, see Release process.