|
| 1 | +# Contributing to Call to Code |
| 2 | + |
| 3 | +This document contains general guidelines for contributing to this project: |
| 4 | + |
| 5 | +- [Prerequisites](#prerequisites) |
| 6 | +- [Getting the Project Source](#source) |
| 7 | +- [Get the App Running](#running) |
| 8 | +- [Pivotal Tracker Workflow](#pivotal) |
| 9 | +- [Git Workflow](#git) |
| 10 | +- [Questions or Problems?](#questions) |
| 11 | + |
| 12 | +## <a name="prerequisites"></a> Prerequisites |
| 13 | + |
| 14 | +Make sure your development environment is properly setup by following the [development environment setup](./DEVELOPER.md) guide. |
| 15 | + |
| 16 | +## <a name="source"></a> Getting the Project Source |
| 17 | + |
| 18 | +> It is recommended to setup ssh. Please [add a new SSH key to your GitHub account](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/). |
| 19 | +
|
| 20 | +### Cloning the repository into your workspace |
| 21 | + |
| 22 | +```bash |
| 23 | +$ cd ~ |
| 24 | +$ mkdir -p workspace && cd workspace |
| 25 | +$ git clone git@github.com:CodeForSocialGood/calltocode.org |
| 26 | +$ cd calltocode.org/ |
| 27 | +``` |
| 28 | + |
| 29 | +### Alternatively, you can fork and clone the repository |
| 30 | + |
| 31 | +1. Learn about forking [here](https://help.github.com/articles/fork-a-repo/). |
| 32 | +2. Fork the [main calltocode.org repository](https://github.com/CodeForSocialGood/calltocode.org). |
| 33 | +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: |
| 34 | +```bash |
| 35 | +$ cd ~ |
| 36 | +$ mkdir -p workspace && cd workspace |
| 37 | +$ git clone git@github.com:<github username>/calltocode.org |
| 38 | +$ cd calltocode.org/ |
| 39 | +$ git remote add upstream https://github.com/CodeForSocialGood/calltocode.org |
| 40 | +``` |
| 41 | + |
| 42 | +## <a name="running"></a> Get the App Running |
| 43 | + |
| 44 | +### Install Dependencies |
| 45 | + |
| 46 | +```bash |
| 47 | +$ yarn |
| 48 | +``` |
| 49 | + |
| 50 | +### Start the app |
| 51 | + |
| 52 | +Use this local build for development: |
| 53 | + |
| 54 | +```bash |
| 55 | +$ yarn db |
| 56 | +$ yarn start:dev |
| 57 | +``` |
| 58 | + |
| 59 | +Use this for simulating the test environment through Docker: |
| 60 | + |
| 61 | +```bash |
| 62 | +$ yarn start |
| 63 | + |
| 64 | +# When finished, stop the app |
| 65 | +$ yarn stop |
| 66 | +``` |
| 67 | + |
| 68 | +*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](./PROBLEMS.md#database).* |
| 69 | + |
| 70 | +### Run tests locally: |
| 71 | + |
| 72 | +```bash |
| 73 | +$ yarn test |
| 74 | +``` |
| 75 | + |
| 76 | +## <a name="pivotal"></a> Pivotal Tracker Workflow |
| 77 | + |
| 78 | +We use [Pivotal Tracker](https://www.pivotaltracker.com) to track our user stories. |
| 79 | + |
| 80 | +- Each story has a **story type**, **story id** and **story name** which will be used in your git workflow |
| 81 | +- There are three different **story types**: **feature**, **bug**, and **chore** |
| 82 | +- The **story id** looks like `#153540677` |
| 83 | +- The **story name** looks like `Encrypt password` |
| 84 | + |
| 85 | +Stories in the backlog that say `Start` are available for starting. |
| 86 | + |
| 87 | +### For feature & bug stories, hit... |
| 88 | + |
| 89 | +- `Start` when you start working. This prevents having two people start separate work on the story. |
| 90 | +- `Finish` when you submit the PR for your work on Github. |
| 91 | +- `Deliver` when the PR gets approved and merged into master. |
| 92 | +- `Accept` when the changes are verified in the test environment. |
| 93 | +- `Reject` when the changes aren't verified in test environment. |
| 94 | + |
| 95 | +### For chore stories, hit... |
| 96 | + |
| 97 | +- `Start` when you start working. This prevents having two people start separate work on the story. |
| 98 | +- `Finish` when you submit the PR *and* it is approved and merged into master. |
| 99 | + |
| 100 | +## <a name="git"></a> Git Workflow |
| 101 | + |
| 102 | +For a detailed example (with screenshots) of our git workflow focused on contributing through a **fork**, see our [detailed contributing guidelines](./CONTRIBUTING_DETAILED.md). |
| 103 | + |
| 104 | +### Stay updated with the master branch |
| 105 | + |
| 106 | +If you have a branch on the main repository's upstream: |
| 107 | + |
| 108 | +```bash |
| 109 | +$ git checkout master |
| 110 | +$ git pull -r |
| 111 | +``` |
| 112 | + |
| 113 | +If you have your own fork and want to update your master: |
| 114 | + |
| 115 | +```bash |
| 116 | +$ git checkout master |
| 117 | +$ git pull -r upstream master |
| 118 | +$ git push origin master |
| 119 | +``` |
| 120 | + |
| 121 | +### Branching |
| 122 | + |
| 123 | +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**: |
| 124 | + |
| 125 | +```bash |
| 126 | +$ git checkout master |
| 127 | +$ git checkout -b <story type>/<story id> |
| 128 | +``` |
| 129 | + |
| 130 | +*Jump back to the [Pivotal Tracker Workflow](#pivotal) section for more information about **story type** and **story id**.* |
| 131 | + |
| 132 | +### Pairing |
| 133 | + |
| 134 | +Always pair when you start a new branch: |
| 135 | + |
| 136 | +```bash |
| 137 | +$ git solo <initials> # if you are working solo |
| 138 | +$ git duet <initials-1> <initials-2> # if you are pairing with someone |
| 139 | +``` |
| 140 | + |
| 141 | +*For more details, go to [developer environment setup](./DEVELOPER.md#rest).* |
| 142 | + |
| 143 | +### Commit Message |
| 144 | + |
| 145 | +Reference the pivotal tracker **story id** for the story you are working on: |
| 146 | + |
| 147 | +```bash |
| 148 | +$ git commit |
| 149 | + |
| 150 | +# below, the commit message is between the ---'s |
| 151 | +--- |
| 152 | +chore: add something |
| 153 | + |
| 154 | +[<story id>] |
| 155 | +--- |
| 156 | +``` |
| 157 | + |
| 158 | +*Jump back to the [Pivotal Tracker Workflow](#pivotal) section for more information about **story id**.* |
| 159 | + |
| 160 | +### Pull Request |
| 161 | + |
| 162 | +Once you are finished with the story, run the tests to make sure your changes are linted and haven't broken any tests: |
| 163 | + |
| 164 | +```bash |
| 165 | +$ yarn test |
| 166 | +``` |
| 167 | + |
| 168 | +Then, push your branch to the repository before creating a pull request: |
| 169 | + |
| 170 | +```bash |
| 171 | +$ git push --set-upstream origin <branch-name> |
| 172 | +``` |
| 173 | + |
| 174 | +You can now create a pull request using the Github web interface. Please format the PR as follows: |
| 175 | + |
| 176 | +- Pull Request Title: `<story type>/<story id> - <story name>` |
| 177 | + - `<story type>` is required and one of the following: |
| 178 | + - **Feature** - a feature story |
| 179 | + - **Fix** - a bug story |
| 180 | + - **Chore** - a chore story |
| 181 | + - `<story id>` is required: |
| 182 | + - For example: `#153540677` |
| 183 | + - `<story name>` is required: |
| 184 | + - For example: `Encrypt password` |
| 185 | + - Full Example: `Feature/#153540677 - Encrypt password` |
| 186 | +- Pull Request Body: no requirements |
| 187 | + |
| 188 | +*Jump back to the [Pivotal Tracker Workflow](#pivotal) section for more information about **story type**, **story id** and **story name**.* |
| 189 | + |
| 190 | +## <a name="questions"></a> Questions or Problems? |
| 191 | + |
| 192 | +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](./PROBLEMS.md) to see if your issue is addressed there. |
0 commit comments