Skip to content

Latest commit

 

History

History
222 lines (151 loc) · 7.34 KB

CONTRIBUTING.md

File metadata and controls

222 lines (151 loc) · 7.34 KB
Raw

Contributing to Call to Code

This document contains general guidelines for contributing to this project:

Please note that this project is released with a contributor code of conduct. By contributing to this project you are also agreeing to abide by its terms.

Prerequisites

Make sure your development environment is properly setup by following the development environment setup guide.

Getting the Project Source

It is recommended to setup ssh. Please add a new SSH key to your GitHub account.

Cloning the repository into your workspace

$ cd ~
$ mkdir -p workspace && cd workspace
$ git clone [email protected]:CodeForSocialGood/calltocode.org
$ cd calltocode.org/

Alternatively, you can fork and clone the repository

  1. Learn about forking here.
  2. Fork the main calltocode.org repository.
  3. Clone your fork of the repository and define an upstream remote pointing back to the main calltocode.org repository that you forked in the first place:
$ cd ~
$ mkdir -p workspace && cd workspace
$ git clone [email protected]:<github username>/calltocode.org
$ cd calltocode.org/
$ git remote add upstream https://github.com/CodeForSocialGood/calltocode.org

Get the App Running

Install Dependencies

$ yarn

Start the app

Use this local build for development:

$ yarn db start
$ yarn start

Note: ports 3000, 27017, and 28017 will need to be available on your machine to run the app. If you run into a problem here, checkout our database troubleshooting.

Run tests locally:

$ yarn test

Pivotal Tracker Workflow

We use Pivotal Tracker to track our user stories.

  • Each story has a story type, story id and story name which will be used in your git workflow
  • There are three different story types: feature, bug, and chore
  • The story id looks like #153540677
  • The story name looks like Encrypt password

Stories in the backlog that say Start are available for starting. They are prioritized top-down, but can really be done in any order.

For feature & bug stories, hit...

  • Start when you start working. This prevents having two people start separate work on the story.
  • Finish when you submit the PR for your work on Github.
  • Deliver when the PR gets approved and merged into master.
  • Accept when the changes are verified in the test environment.
  • Reject when the changes aren't verified in test environment.

For chore stories, hit...

  • Start when you start working. This prevents having two people start separate work on the story.
  • Finish when you submit the PR and it is approved and merged into master.

Git Workflow

If you're working through a fork: see our detailed contributing guidelines which outlines our git workflow (and has screenshots), focused on contributing through a fork.

Stay updated with the master branch

If you have a branch on the main repository's upstream:

$ git checkout master
$ git pull -r

If you have your own fork and want to update your master:

$ git checkout master
$ git pull -r upstream master
$ git push origin master

Branching

When you start new work, always create a new branch off of the master branch, using the corresponding pivotal tracker story type and story id:

$ git checkout master
$ git checkout -b <story type>/<story id>

Jump back to the Pivotal Tracker Workflow section for more information about story type and story id.

Pairing

Always pair when you start a new branch:

# If you are working solo
$ git solo <initials>

# If you are pairing with someone
$ git duet <initials-1> <initials-2>

For more details, go to developer environment setup.

Commit Message

Reference the pivotal tracker story id for the story you are working on:

$ git commit

# Below, the commit message is between the ---'s
---
chore: add something

[<story id>]
---

Jump back to the Pivotal Tracker Workflow section for more information about story id.

Pull Request

Once you are finished with the story, run the tests to make sure your changes are linted and haven't broken any tests:

$ yarn test

Then, push your branch to the repository before creating a pull request:

$ git push --set-upstream origin <branch-name>

You can now create a pull request using the Github web interface. Please format the PR as follows:

  • Pull Request Title: <story type>/<story id> - <story name>
    • <story type> is required and one of the following:
      • Feature - a feature story
      • Fix - a bug story
      • Chore - a chore story
    • <story id> is required:
      • For example: #153540677
    • <story name> is required:
      • For example: Encrypt password
    • Full Example: Feature/#153540677 - Encrypt password
  • Pull Request Body: no requirements

Once you have submitted your pull request (PR), it needs to be approved and updated with the master branch's latest changes with all conflicts resolved before it can be merged. See the section below on how to deal with this.

Jump back to the Pivotal Tracker Workflow section for more information about story type, story id and story name.

Branch Updating and Conflicts

If you need to resolve conflicts with master or update your branch with the latest changes from master after you've already pushed changes and possibly after you've submitted a pull request, it is best to do the following:

Update master

$ git checkout master
$ git pull -r
$ git checkout <your branch>
$ git rebase master

Resolve conflicts (if there are any)

# Repeat this step until there are no more conflicts
$ git status
# Follow instructions printed by git, then
$ git rebase --continue

Re-push your changes

$ git push -f

This is a good practice because it will rebase your branch's changes on top of the latest changes on the master branch, avoiding any ugly/noisy merge commits on your branch.

In some cases you can update your branch using the "Update branch" button inside of your open pull request. This is available when there are no (complex) conflicts between your branch and master, and will always create an "ugly" merge commit on your branch. In our case, this doesn't really matter because we squash the commits in our PRs into one commit when we merge into master, but the above workflow is necessary when conflicts are too complex to be resolved through the browser.

Questions or Problems?

If you're stuck on something, don't be afraid to ask around in Slack! You can also check out our list of Common Problems to see if your issue is addressed there.