GitHub Milestones and Labels are a great way to organise a busy source control repository, and curate your development streams and projects.
This versatile organisation layer built directly into the GitHub platform is a highly effective way to pull individual issues, features and projects together into a single release, while planning your subsequent releases at the same time.
Use Milestones in conjunction with Gearset to organise your releases, keeping feature independence without losing the structure of your release building strategy.
Creating a Milestone
To find Milestones, navigate to this issues page of your GitHub repository and open the Milestones page.
Create a new Milestone and populate the Milestone with a few key pieces of information, like the purpose, release date and associated business needs.
Save the Milestone.
Using Milestones with pull requests
Start by committing your "in progress" work to a new feature branch, using Gearset's intuitive UI. You can find out more about doing this here.
After you have made your commit and you're happy with your new feature branch, it's time to create a pull request.
We recommend using pull request templates, to take advantage of some more great native functionality within GitHub (Not sure where to start? Try using this template to get started).
### Is this intended for a release milestone or hotfix?
Please indicate:
### Pre Dev Integration checks
- [ ] Post deployment data template prepared (if nesc)
- [ ] PR description completed with developer notes
- [ ] Any HTML or Java issues detected and remediated?
- [ ] Associated with the correct Milestone and labelled?
### Pre UAT checks
- [ ] Post deployment data template deployed to Dev Int (if nesc)
- [ ] Feature has been tested fully in Dev Int
- [ ] Post deployment data template prepared (if nesc)
### Pre-release checks
- [ ] Post deployment data template deployed to UAT (if nesc)
- [ ] Feature has been fully tested in UAT
- [ ] The Product Owner accepts the changes
**A reminder of our Definition of Done**:
- [ ] Tests are added and are passing
- [ ] The Product Owner accepts the changes
- [ ] The documentation is updated
- [ ] Code is fully reviewed at every stage, and has passed all status checks per Gearset settings
Once your pull request has been created, you can use associate it with the appropriate Issue, Label(s) and Milestone.
Assign your reviewers or review group, and allow Gearsets automated quality controls to kick in.
Once the review is complete and all status checks are successful the pull request can be promoted.
Promoting your Milestone
It's best practice to promote your pull request as soon as it is reviewed and ready. If there are other pull requests which are also ready to be promoted and are part of the same Milestone, you can search for them. You can also search for them by their associated Label.
After selecting the pull requests which you are ready to promote and deploy, click promote.
This will merge all the selected pull requests into a local branch, and then run a validation against the target org for the sum of those changes (for more detail about how we do this please see this doc).
After the validation is successful, the features are merged into the environment branch and deployed.
You can now test that the work connected with that Milstone in that org, while Gearset begins automatically validating its components against the next environment in your Pipeline.
Because the pull request template and Milestone stay attached to the feature branch, you can continue to add information to it as it is promoted through your Pipeline, and make sure the pre and post deployment steps are completed before you approve it for promotion to the next environment.
Creating a release with your Milestone
After the components of your Milestone have been promoted through the Pipeline, it is time to add them to the release branch.
We have kept the features belonging to this Milestone separate until now for several reasons:
By having less to review, reviews of the individual PRs could be done more rapidly and with greater accuracy.
If feedback came from testing that new components needed to be added or removed to the feature branch, that could be dealt with without affecting other in-flight features.
Features could be removed from or added to the Milestone with ease without affecting the stability of the final product.
By the time these individual features have had a pull request opened to the main branch, they have been thoroughly tested, validated and reviewed in each environment, and they're ready to be added to the final version of the release.
To select and add the pull requests to the release branch, filter for them and select them.
After selecting the pull requests, add them to the release branch. If you have not already created one, you can create a release with the same name as your Milestone.
Once the release branch has been created, it will automatically begin validation against the Production org, to confirm that all the features that make up this particular Milestone are valid and can be deployed successfully.
Make sure you have indicated the Milestone(s) these features are linked to on the pull request.
More features can be added to this release branch once it is created, so if there are other components of the Milestone still undergoing testing or awaiting review, they can be added later as they're promoted up to the final environment.
The release branch will be reviewed as any pull request should be, and the user can confirm that all of the features they were expecting to be added for this Milestone have indeed been added.
Deploying your release
After all the validation and review is complete, you can promote the release (if you would like to schedule this, use this option).
Use the "sync" feature within Gearset to make sure that the entirety of the release that has just been deployed to Production is also present in your lower sandbox environments (to learn more about this feature check out this doc).
Tracking which Milestones have made it to Production
Once you have deployed your release to Production there will be a record of this happening in your Pipelines promotion history.
You can view this in greater detail by clicking "View all promotion history".
