Github Flow: Committing Code
Proposed guideline for steps to follow for contributing to the ezCGP repository
We ideally want to break up all dev work into small, cohesive tasks in the form of Github issues. Issues provide a good place to share and discuss feature details. They also help with goal setting and tracking the velocity of the team.
Branch-per-issue workflow -- for each issue you work on, create a development branch. You do all the implementation and testing on this branch. Ideally, you would be the only person to push code to this branch. Remember to branch off of the most recent "master" branch (this could just be the stable branch for the semester, like 2020F-BaseCodeDevelopment).
git branch feature/Issue#-featureName
git checkout feature/Issue#-featureName
Besides any testing specific to your code changes, you can run the sample problem to make sure everything works as expected:
$ python main.py -p problem_multiGaussian -n "test run" -s 9 -t -d
We want to create a more robust testing pipeline in the future.
When you have finished the issue and are happy with the state of your branch, you can go ahead and make a pull request. You want to provide a brief description of the changes you made in the description of your pull request and link to the related issue (Ideally you will also only ever make one pull request per branch and per issue). You can now request review from other members on the team. We want to have at least one approved review before merging a pull request. You should also include a brief description of what you did to test your changes and provide results from the tests for the reviewers to look at.
After receiving a review, you can answer any questions the reviewer had and address any requested changes. You can go ahead and merge your changes once you receive approval. After merging, remember to delete your branch from remote so that the remote only contains active branches at any point.
Some questions to ask while reviewing code:
- Does the code work?
- Is the code easy to maintain?
- Is it easy to understand?
Some things to keep in mind:
- Be Constructive: Make sure to go over your comments before submitting your review
- Code suggestions: It is easier to show than tell
- Learning opportunity: Code reviews are a great place to learn, both for the author and the reviewer
Some additional guidelines on code reviews by Google here and here.
