- Fork the repo
- Pull/rebase and changes from organization master repo
- Cut a namespaced feature branch from master with specific prefix (see prefix examples below)
- Make commits to your feature branch. Prefix each commit like so: (see examples below)
- When you’ve finished with your fix or feature, rebase upstream changes into your feature branch. After resolving any conflicts, push your branch to your personal Github to check the build with Travis CI. If it passes, move on to #6, otherwise fix the code/tests and repeat #5 until all tests pass.
- To submit your changes to the central repo, push your branch up to the central repo, then submit a pull request to merge with the master branch. Include a description of your changes.
- Your pull request will be reviewed by another maintainer. The point of code reviews is to help keep the codebase clean and of high quality and, equally as important, to help you grow as a programmer. If your code reviewer requests you make a change you don't understand, ask them why.
- Fix any issues raised by your code reviwer, and push your fixes as a single new commit to your feature branch.
- Once the pull request has been reviewed, it will be merged by another member of the team. Do not merge your own commits.
- DO NOT MERGE YOUR OWN COMMITS!
Note:
- Delete all extra branches. Once a branch has been merged to master, delete it from the central repo and your own!
- Don't attempt a pull request on the central repo until you've tested the build on your own forked repo
Use github’s interface to make a fork of the repo, then add that repo as an upstream remote:
git remote add upstream https://github.com/news-stand/news_stand.gitYour branch should follow this naming convention:
- bug/...
- feat/...
- test/...
- doc/...
- refactor/...
These commands will help you do this:
# Creates your branch and brings you there
git checkout -b `your-branch-name`Prefix each commit like so
- (feat) Add a new feature
- (fix) Fix inconsistent tests [Fixes #0]
- (refactor) Refactor/improve existing code or tests
- (cleanup) Remove stray logs or comments
- (test) Create tests
- (doc) Create or update documentation
Make changes and commits on your branch, and make sure that you only make changes that are relevant to this branch. If you find yourself making unrelated changes, make a new branch for those changes.
- Commit messages should be written in the present tense; e.g. "Fix continuous integration script".
- The first line of your commit message should be a brief summary of what the commit changes. Aim for about 70 characters max. Remember: This is a summary, not a detailed description of everything that changed.
- If you want to explain the commit in more depth, following the first line should be a blank line and then a more detailed description of the commit. This can be as detailed as you want, so dig into details here and keep the first line short.
Once you are done making changes, you can begin the process of getting your code merged into the main repo. Step 1 is to rebase upstream changes to the master branch into yours by running this command from your branch:
git pull --rebase upstream masterThis will start the rebase process. You must commit all of your changes before doing this. If there are no conflicts, this should just roll all of your changes back on top of the changes from upstream, leading to a nice, clean, linear commit history.
If there are conflicting changes, git will start yelling at you part way through the rebasing process. Git will pause rebasing to allow you to sort out the conflicts. You do this the same way you solve merge conflicts, by checking all of the files git says have been changed in both histories and picking the versions you want. Be aware that these changes will show up in your pull request, so try and incorporate upstream changes as much as possible.
You pick a file by git adding it - you do not make commits during a
rebase.
Once you are done fixing conflicts for a specific commit, run:
git rebase --continueThis will continue the rebasing process. Once you are done fixing all conflicts you should run the existing tests to make sure you didn’t break anything, then run your new tests (there are new tests, right?) and make sure they work also.
If rebasing broke anything, fix it, then repeat the above process until you get here again and nothing is broken and all the tests pass.
For testing, we have separate client- and server-side test suites.
- Client-Side Testing
- Technologies/Libraries:
- Debugging:
- Click the 'debug' button on the Karma browser and open up the Chrome Dev Tools console
# karma client must be installed globally to run tests
npm install -g karma-cli# to run the tests
karma start- Server-Side Testing
- Technologies/Libraries:
# to run the tests
npm run testWe use Travis CI to test our builds when submitting to GitHub. Be sure to # for an account and enable all necessary environment variables in your settings or else the build will fail.
When you have a branch ready to test, push it up to your fork and let Travis run a build on it. If it fails, make additional changes on your local repo before testing again. The tests will be run again when you make a pull request later. Once you have a passing build, delete the branch on your forked repo.
# to check the build with Travis
git push origin <branch_name># to delete the branch on your origin repo once the build passes
git push -d origin <branch_name>For more details on Travis, please look at the documentation at:
./documentation/travis.mdOnce you have a passing build with Travis, push the branch up to the central repo.
# to check the build with Travis
git push upstream <branch_name>Make a clear pull request from the new branch to the upstream master branch, detailing exactly what changes you made and what feature this should add. The clearer your pull request is the faster you can get your changes incorporated into this repo.
Travis will do a build of your branch and run the tests. If they don't pass, the branch won't be merged.
Two other people should give your changes a code review, and once they are satisfied one of them will merge your changes into upstream. If only one person has completed a code review and five hours have passed, then that reviewer can merge your changes into upstream without waiting for a second review. The goal is to give as many team members as possible a chance to see what's going on in every corner of the codebase. Alternatively, they may have some requested changes. You should make more commits to your branch to fix these, then follow this process again from rebasing onwards.
Once you get back here, make a comment requesting further review and someone will look at your code again. If they like it, it will get merged, else, just repeat again.
Once a pull request gets merged to master, Travis will automatically deploy to the Heroku staging app for the whole team's review.
Thanks for contributing!
- Uphold the current code standard:
- Keep your code DRY
- Apply the boy scout rule
- Follow STYLE-GUIDE.md
- Run the all tests before submitting a pull request.
- Tests are very, very important. Submit tests if your pull request contains
new, testable behavior.
- We wil require at least 1 test per pull request where possible
This is just to help you organize your process
- Did I cut my work branch off of master (don't cut new branches from existing feature brances)?
- Did I follow the correct naming convention for my branch?
- Is my branch focused on a single main change?
- Do all of my changes directly relate to this change?
- Did I rebase the upstream master branch after I finished all my work?
- Did I write a clear pull request message detailing what changes I made?
- Did I get a code review?
- Did I make any requested changes from that code review?
If you follow all of these guidelines and make good changes, you should have no problem getting your changes merged in.