Your project's source code is its single most important artifact. The loss or corruption of your code base is a catastrophic event that can impact not just your project, but also your reputation as a professional developer.
This makes it critical that your team defines the process that everyone on the team will rigidly adhere to when making and promoting changes. The good news is that despite its importance, establishing a solid Git Workflow isn't difficult and both Git and GitHub are battle-tested tools.
Chingu requires that our teams maintain their projects in GitHub. While there are other alternatives, such as BitBucket and GitLab, centralizing on a common cloud-based service greatly simplifies the process of familiarizing Chingus new to git and cloud-based source code management. It also simplifies our monitoring process since there's only one such service to interface with.
Git maintains a record of your participation and activity against your team's git repo - commits, issues, pull requests, and pull request reviews to name just a few. However, in order to correctly attribute the work you perform to you they have to know who you are. This is important since prospective employers will use the metrics in your GitHub profile to evaluate your capabilities, based on your project work.
To ensure that git and GitHub properly collect and attribute your activities follow these instructions to set up your GitHub user name and email address. Make sure that the email address you set up in your local git matches the email address in your GitHub Profile.
There are multiple workflow models you can choose to adopt, but if you are new to Git and GitHub, one type of Git workflow is presented here. This model is based on the assumption that your team will set up a skeleton repo in GitHub from which all team members will then clone to their computers.
A three-level hierarchy of branches is created, through which changes are promoted.
- Working branches: Individual branches created by each developer when
they are working on changes and bug fixes. There are 3 basic types of
branches: fix, feature, and refactor. For example:
feature/course-review. - Development: Reflects the code for the next release. Developers work in working branches, which are then pulled into this branch. All code pulled into this branch must be tested and undergo peer review as part of the PR process.
- Master: Only updated from the development branch Pull Requests. This branch always reflects the current production release that is seen by live users.
- Once the skeleton repo is built in GitHub, team members will clone it to their individual computers. Working branches are created for specific features and tasks (like bug fixes).
- All normal development activities occur on team members' individual computers. Commits should be frequent and each commit should have a discrete, atomic purpose.
- Changes should be frequently pushed to the matching working branch on GitHub. This ensures that if a computer is lost, stolen, or malfunctions, your work will still be available to the rest of your team.
- From time to time, you may also need to pull working branches to your individual computer. For example, you'll need to do this if/when you help another team member with one of their tasks.
- Once a feature has been unit tested, a Pull Request (PR) should be created to fold it into the development branch. It's always a good idea to require that PRs be reviewed by another member of the team. This helps to ensure that the quality of the app is maintained.
- When a group of features are ready to be promoted to Production, they should be thoroughly tested together. Then, a Pull Request should be created in order to move them into the master branch which reflects the code base that's in Production or soon to be promoted to Production.
- Once the PR to the master branch has been completed, you are then ready to release its contents into your Production runtime environment.
- Include the purpose of the Pull Request. For example: "This makes login/register windows close when clicking outside the box".
- If the change is visual, make sure to include a screenshot or GIF.
- Consider providing an overview of why the work is taking place (with any relevant links); don’t assume familiarity with the history.
- Be explicit about what feedback you want, if any: a quick pair of eyes on the code, discussion on the technical approach, critique on design, a review of copy, etc..
- Be explicit about when you want feedback. If the Pull Request is a work in progress, say so. A prefix of
[WIP]in the title is a simple, common pattern to indicate this. - @mention individuals that you specifically want to involve in the discussion, and mention why.
- Understand the issue that is being fixed, or the feature being added. Check the description on the pull, and check out the related issue. If you don’t understand something, ask the submitter for clarification.
- Reproduce the bug (or the lack of feature) in the destination branch, usually
development. The referenced issue will help you here. If you’re unable to reproduce the issue, contact the issue submitter for clarification. - Check out the pull and test it. Does the feature work? Is the issue fixed? Does it have any nasty side effects? Try to create suspect inputs. If it operates on the value of a field, try things like strings (including an empty string), null, numbers, or dates. Try to think of edge cases that might break the code.
- Merge the target branch. It is possible that tests or the linter have been updated in the target branch since the pull was submitted. Merging the pull could cause the core to start failing.
- Read the code. Understanding the changes will help you find additional things to test. Contact the submitter if you don’t understand something.
- Go line-by-line. Are there style guide violations? Strangely named variables? Magic numbers? Do the abstractions make sense to you? Are things arranged in a testable way?
- Speaking of tests: are they there? If a new function was added, does it have tests? Do the tests, well, TEST anything? Do they just run the function or do they properly check the output?
- Suggest improvements. If there are changes needed, be explicit and comment on the lines in the code that you’d like changed. You might consider suggesting fixes. If you can’t identify the problem, animated screenshots can help reviewers understand what’s going on.
- Hand it back. If you found issues, re-assign the submitter to the pull to address them. Repeat until mergeable.
- Hand it off. If you’re the first reviewer and everything looks good but the changes are more than a few lines, hand the pull to someone else to take a second look. Again, try to find the right person to assign it to.
- Merge the code. When everything looks good, merge into the target branch. Check the labels on the pull to see if backporting is required, and perform the backport if so.