-
Notifications
You must be signed in to change notification settings - Fork 0
10: GitHub and Cloud.gov Pages (FKA Federalist)
The site code and content is stored in GitHub. A full GitHub tutorial is beyond the scope of this documentation, but we'll cover some basics about our team's use of GitHub for this project.
If you don't have access to the 10x-website repository, you'll need to request access from a repository admin.
GitHub uses branches to manage contributions from multiple team members. All content, code and design changes are staged in these feature branches. Once approved, those changes are merged into the main branch.
When you start working, pull down ("fetch") any changes to the site since you last contributed. All team members from engineering, product, design, and content are contributing to the main branch, where everyone's work ends up.
It's good practice to try to keep your branches as up to date with main as possible. This helps reduce merge conflicts. Merge conflicts happen when two or more people change the same part of the site and both try to merge. The older your branch gets, the more likely someone else on the team has changed something related to what you're working on.
Once you pull changes from the remote repository in GitHub, you can create a new feature branch for your work. Most of the time, you'll want to create your branch from the most recent version of main. You can name the branch anything you want, but we generally use the naming convention of initials-type of changes. (Example: mao-about-updates).
Once you've made your changes or contributions, you can "push" your changes to the remote repository. This just means that the changes you've made in your branch will be available to other team members on GitHub and a site preview will build in Cloud.gov Pages for your review.
For your changes to get into the pipeline for release to the website, they need to be thoroughly reviewed in the feature branch. Once everything looks good, you'll want to open a pull request. A pull request is a request to the team to merge your changes into the main branch. When merged, your changes will be combined with the rest of the team's changes to the site.
When you open a pull request in GitHub, it's best to include the following:
- Describe your changes or additions, including rationale or context.
- Include a preview link so reviewers can preview your changes on a working version of the website. Ideally, you should include a direct preview link for any new or edited pages to make the reviewer's job easier.
- Add a reviewer or reviewers to take a look at your changes. Tag reviewers in Slack, since not everyone checks their email.
- If the changes correspond to a GitHub issue, include
Fixes #XX, filling in the issue number so reviewers can easily link back to it and so that the issue is automatically closed once the feature branch is merged into main. - Make sure CircleCI tests pass (if CircleCI tests fail, you may want to work with an engineer to find out why).
- Don't merge your own pull requests! It's good practice to have someone else merge your pull request (usually one of the reviewers).
After the pull request is merged into main:
- Close the corresponding GitHub issue, if fully resolved by your changes and not automatically closed by your PR.
We use Cloud.gov Pages to build the website and deploy the site. Pages creates a preview for every branch pushed to the repository. With access to Pages, you'll be able to track branch builds and errors, and you'll be able to access preview links.