Git Branching and Pull Request Workflow
- Anurag Kusumba (Deactivated)
- Jason Chung
- Jai Dhaliwal (Unlicensed)
This document assumes that you have a basic understanding of git and know how to use git CLI.
Purpose
This document provides the recommended pull request workflow and branching strategy to contribute to CHEFS and collaborate with the Forms Design and Submissions (Forminators) team to ensure that only stable and expected features are added to the repository.
Fork Repository from the bcgov Codebase
The recommended approach for contributing to CHEFS is to submit pull requests from a ‘technical user’ account. In this case, all development is first merged onto the technical user’s fork of CHEFS to minimize merge conflicts and ensure that any bugs or breaking changes are caught before the merge with CHEFS is requested.
Create a technical user:
A new ‘technical' GitHub account should be created to fork the CHEFS repository in order to enhance collaboration and remove dependency on any individual within a team. In the following example, the Forminator team’s technical account 'bcgov-citz-ccft' will be used for demonstration purposes.
Create a new repository “bcgov-citz-ccft/common-hosted-form-service” forked from the main bcgov/common-hosted-form-service repository. Note that ‘bcgov-citz-ccft' is the Forminator’s technical user account which would be replaced by your team’s technical account.
After forking the common-hosted-form-service repository, the developers will only work through the forked repository, in this case, bcgov-citz-ccft/common-hosted-form-service, and contribute by raising a pull request via this repository.
Branching Strategy
In order to ensure a stable product is released to the CHEFS codebase, the Forminators team implements the following branching strategy, which is also the recommended approach for our partners:
Name of the branch | Description |
|---|---|
Main | The |
Develop | The development team uses this branch to test their code and create new feature branches. The |
Feature | In this branch, the developers work on their respective feature/bug. This usually corresponds to a Jira ticket for each feature/bug that a developer will work on. This is a short term branch that is deleted once a pull request is approved. The naming convention for feature branches is as follows:
|
Pull Request Workflow
Start by cloning the technical account’s newly forked repository onto your local machine. In this example, bcgov-citz-ccft/common-hosted-form-service.
git clone https://github.com/bcgov-citz-ccft/common-hosted-form-service.git
Next, create a develop branch which will be the basis for the feature branches:
git checkout develop
Create feature/bug fix branches based on the Jira backlog following the naming convention:
git checkout -b feature/<ticket id>-<ticket title in short>
When you are done working locally, commit and push your changes onto the feature branch:
git add .
git commit -m "your commit message here"
git push
Pull Request Process Within the Forked Repository:
Once the contributions are pushed, raise a pull request to merge the corresponding feature branch onto the develop branch. It is recommended that the contributions be peer-reviewed before creating the pull request.
The pull request is then reviewed and merged with the develop branch based on the acceptance criteria.
This pull request (PR) approval and testing process on the forked repository acts as an “acceptance criteria” or “PR-ready” to raise a PR onto the CHEFS repository. Merged code on the develop branch acts as the smoke/sanity check, and if passed, it is merged onto the main or master branch on the technical account’s fork (inside the bcgov-citz-ccft/common-hosted-form-service repository.)
Raise a PR from the Fork to CHEFS:
Now, the changes contained in the forked repository need to be merged with the CHEFS repository. To do this, submit a pull request to the CHEFS repository.
After submitting the PR, the Forminators team will review the changes. It is good practice to mention a Forminators team member specifically when submitting the PR to ensure that they see it. This can be done by using @their-github-username-here in a comment while raising the PR.
Complete the PR template by adding a detailed description, contribution type, and ensure that all steps of the checklist have been completed, which are as follows:
I have read the CONTRIBUTING doc
I have checked that unit tests pass locally with my changes
I have run the npm script lint on the frontend and backend
I have added tests that prove my fix is effective or that my feature works
I have added the necessary documentation (if appropriate)
I have approval from the product owner for the contribution in this pull request
Deploying to the PR Environment on GitHub
Pull requests that are made from a branch within the bcgov/common-hosted-form-service repository are the only PRs that are deployed to the GitHub PR environment, for this reason, if your team does not have a means of hosting CHEFS, i.e. your own OpenShift namespace, a dedicated branch will be allocated for your team through which PRs will be created for the master branch. Your team members will be given collaborator access to contribute to CHEFS.
Once your contributions are ready to be pushed, raise a pull request onto your team’s branch on the CHEFS repository and we will merge it with the master branch following our approval and acceptance criteria.
Acceptance Criteria
The PR will be automatically deployed using Github’s PR environment into the Openshift dev environment and will start test automation. Our team will not review the code until the automated tests have passed. Once the tests have passed, the product owner and UI/UX designers will review the contribution within the PR environment. The PO (product owner) will verify that the contribution has been approved, and a UI/UX designer will test the interface of the application to ensure that it aligns with the presented and approved wireframes/prototypes/mockups in the NEXUS planning session. If not, the PR may be rejected and additional feedback will be provided accordingly.
After the PO and UI/UX designer have approved the PR, the developers will begin the technical review based on the following criteria:
Code: The code will be reviewed to ensure it implements best practices, is syntactically correct and aligns with the paradigm of the existing application. The stability and performance of the feature or the bug fix will be evaluated.
Tests: Additional tests must be provided to verify that your feature is working as expected or the bug fix has solved the issue.
Documentation: Documentation and code comments must be provided for all features, explaining their capability and usage instructions to ensure that we are able to support the users of the feature.
Following the technical review, the PR may be accepted or rejected. In case the pull request is declined, additional comments will be provided so that developers may modify the pull request accordingly. If accepted, the pull request will be merged with the master branch, and automatically deployed to the dev environment.
At this point, our team will push it up to the test environment for further testing. Once the feature is ready for production, our team lead will deploy it to the production environment where the changes will be visible to CHEFS users.
Pull Request Limitations
When a Pull Request (PR) is opened from a branch within the bcgov repository into the master branch in the bcgov repository; GitHub actions will deploy an instance of CHEFS into our OpenShift namespace. GitHub does not have a limitation on the number of PRs that can be opened, but the Forminators team has a resource limit on the number of resources we have allocated to our OpenShift namespace. We are currently limiting the number of PRs that can be opened to 2 PRs per team, while we reserve 2 for hotfixes, and 2 for emergencies.