“How do I contribute code to this project?”
First off, take a moment to review our Best Practicesbefore writing or submitting any code.
No direct changes should be pushed to the Acquia repository. The process of syncing these repositories is managed transparently in the background.
The recommended workflow resembles a Gitflow Workflow with the follow specifics -
- All development is performed against a
- Completed features are merged into a
releasebranch until a new release needs to be made. Additional QA testing should be made against this branch and fixed inline, if needed.
- Each commit to the
masterbranch is tagged with a release number, named either based on sprints (e.g.
24.0) or date (e.g.
- Any hotfixes are merged directly into a
hotfixbranch, which can then be merged to
Beginning work locally¶
- Pull a ticket in JIRA
- Create a new local feature branch named according to the following pattern:
abc-123-short-descWhere "ABC" is the Jira prefix of your Jira project and "123" is the ticket number for which the work is being performed.
- Make your code changes.
- Commit your changes. Each commit should be logically atomic, and your commit messages should follow the pattern: "ABC-123 A grammatically correct sentence ending within punctuation."
Creating a Pull Request¶
For any work, pull requests must be created for individual tasks and submitted for review. Before submitting a pull request, be sure to sync the local branch with the upstream primary branch -
git checkout develop git pull upstream develop git push origin develop git checkout -b XXX-<new-issue-branch> develop
If you created many small commits locally while working through a ticket, you should clean the history so that it can be easily reviewed. You can combine these commits using
git rebase -i upstream/master
Pull requests should never contain merge commits from upstream changes.
Push your feature branch to your fork of the upstream repository, and 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.
In order to enforce consistency on a project, a pull request template can also be configured using
git config --global --add hub.pull-request-template-path ~/.pr-template
Resolving merge conflicts¶
Merge conflicts result when multiple developers submit PRs modifying the same code and Git cannot automatically resolve the conflict. For instance, if two developers add update hooks to the same module at the same time, these will necessarily conflict, because update hooks must be numbered in a defined sequence.
Developers are responsible for fixing merge conflicts on their own PRs. Follow this process to resolve a merge conflict:
- Fetch upstream history:
git fetch upstream
- Check out the branch against which you opened your PR (e.g. master):
git checkout master
- Make sure it matches upstream:
git reset --hard upstream/master
- Check out your feature branch:
git checkout feature/foo
- Merge master (this is where the magic happens):
git merge master
- At this point, Git will complain about a merge conflict. Run
git statusto find the conflicting file(s).
- Edit the files to fix the conflict. The resources at the end of this section provide more information on this process.
git addto add all of the files you fixed.
- Finally, run
git committo finish the merge, and
git push origin feature/footo update the PR.
Integration (merging pull requests)¶
Two versions of the integration workflow are recommended -
- Integration manager
- Peer review
In either workflow, no one should ever commit their own code to the primary working branch.
This model requires one (or more) lead developers to take the responsibility of merging all pull requests. This ensures consistency in quality control as well as identifying any potential issues with related, open pull requests.
A small group of one or more person(s) is selected to be integrators. All commits are reviewed by this group. If work is done by an integrator, their work should be reviewed by a fellow integrator (as if they were a developer).
This model removes the bottleneck of designated integrators, but still eliminates commits directly to the working branch. In short, every commit is reviewed by a developer other than the one submitting the original commit.
After a Pull Request has been submitted or merged, our continuous integration solution will automatically build a site artifact, install an ephemeral instance of Drupal, and execute tests against it. For more information on the build process, please see the Continuous Integration documentation.
Deployment on Cloud¶
Once work has been merged on GitHub and tested via the CI solution, a separate production-ready built artifact will be built and deployed to Acquia Cloud. This can be done either manually or automatically.
Please see deploy.md for more information.
A designated Release Master will perform the release to production. This is typically the project’s Technical Architect. See the Release Process document for detailed information.