|
| 1 | +# For Contributors |
| 2 | + |
| 3 | +If you are interested in contributing to this repository, please read and follow |
| 4 | +these guidelines. |
| 5 | + |
| 6 | +## Contents |
| 7 | + |
| 8 | +* [Design](#design): An overview of the repository and its structure |
| 9 | +* [Workflow Conventions](#workflow-conventions): Git workflow conventions that |
| 10 | + contributors must follow in order to contribute to the project |
| 11 | + * [Forking Workflow](#forking-workflow): The macro level workflow convention |
| 12 | + * [Gitflow Workflow](#gitflow-workflow): The micro level workflow convention |
| 13 | +* [Style Guide](#style-guide): Text and coding conventions that contributors |
| 14 | + must follow in order to contribute to the project |
| 15 | +* [License](#license) |
| 16 | + |
| 17 | +## <a name="design"></a> Design |
| 18 | + |
| 19 | +There is a README file in pretty much every directory. The repository is |
| 20 | +designed to be more or less self-documenting, with any questions that may arise |
| 21 | +answered in a nearby README file or, in the case of software and scripts, |
| 22 | +in-file comments. |
| 23 | + |
| 24 | +The [c-implementation](c-implementation/README.md) and |
| 25 | +[python-implementation](python-implementation/README.md) directories contain TAB |
| 26 | +implementations in C and Python. The [c-examples](c-examples/README.md) and |
| 27 | +[python-examples](python-examples/README.md) directories contain examples that |
| 28 | +use the C and Python implementations of TAB. The [images](images/README.md) |
| 29 | +directory contains image files used for documentation or other purposes. |
| 30 | + |
| 31 | +## <a name="workflow-conventions"></a> Workflow Conventions |
| 32 | + |
| 33 | +At a macro level, development follows the [Forking Workflow](#forking-workflow). |
| 34 | +This level of development consists of interactions between contributors (e.g. |
| 35 | +pull/merge requests, forks/clones, etc). At a micro level, development follows |
| 36 | +the [Gitflow Workflow](#gitflow-workflow). This level of development consists of |
| 37 | +actions by a single contributor (e.g. branching, commits, etc). |
| 38 | + |
| 39 | +### <a name="forking-workflow"></a> Forking Workflow |
| 40 | + |
| 41 | +The Forking Workflow consists of three initialization steps and six iterative |
| 42 | +steps. This project's macro workflow is based on the Forking Workflow described |
| 43 | +at [https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow). |
| 44 | + |
| 45 | + |
| 46 | + |
| 47 | +**Initialization steps** |
| 48 | + |
| 49 | +i) User A initializes Local Repository A and pushes it to Remote Repository A. |
| 50 | +```bash |
| 51 | +usera$ mkdir /path/to/repository/ && cd /path/to/repository/ |
| 52 | +usera$ git init |
| 53 | +usera$ git config user.name "User A" |
| 54 | +usera$ git config user.email "[email protected]" |
| 55 | +usera$ git remote add origin https:// [email protected]/usera/repository.git |
| 56 | + # Create a README file |
| 57 | +usera$ git add README.md |
| 58 | +usera$ git commit -m "Adds README" |
| 59 | +usera$ git push -u origin master |
| 60 | +``` |
| 61 | + |
| 62 | +ii) User B forks Remote Repository A in order to create Remote Repository B. |
| 63 | + |
| 64 | +iii) User B clones Remote Repository B in order to create Local Repository B. |
| 65 | +```bash |
| 66 | +userb$ git clone https:// [email protected]/userb/repository.git |
| 67 | +userb$ cd repository/ |
| 68 | +userb$ git config user.name "User B" |
| 69 | +userb$ git config user.email "[email protected]" |
| 70 | +userb$ git remote add upstream https:// [email protected]/usera/repository.git |
| 71 | +``` |
| 72 | + |
| 73 | +**Iterative Sequence** |
| 74 | + |
| 75 | +0) User B fetches and merges upstream changes and makes changes according to |
| 76 | + the [Gitflow Workflow](#gitflow-workflow). |
| 77 | + |
| 78 | +1) User B pushes changes made to Local Repository B to Remote Repository B. |
| 79 | +```bash |
| 80 | +userb$ git push origin branch-name |
| 81 | +``` |
| 82 | + |
| 83 | +2) User B submits a pull request from the updated branch in Remote Repository B |
| 84 | + to an appropriate target branch in Remote Repository A. See the |
| 85 | + [Gitflow Workflow](#gitflow-workflow) section for a list of appropriate |
| 86 | + merges. |
| 87 | + |
| 88 | +3) User A fetches the changes submitted by User B from Remote Repository B to |
| 89 | + Local Repository A. |
| 90 | +```bash |
| 91 | +usera$ git fetch https:// [email protected]/userb/repository.git branch-name |
| 92 | +usera$ git checkout FETCH_HEAD |
| 93 | +``` |
| 94 | +User A tests the code for acceptability. Upon a successful test, the changes |
| 95 | +are merged into the indicated target branch in Local Repository A. |
| 96 | +```bash |
| 97 | +usera$ git checkout target-branch |
| 98 | +usera$ git merge --no-ff FETCH_HEAD |
| 99 | + # omit --no-ff if merging develop into develop |
| 100 | +``` |
| 101 | + |
| 102 | +4) User A pushes the merged changes from Local Repository A to Remote |
| 103 | + Repository A. |
| 104 | +```bash |
| 105 | +usera$ git push origin target-branch |
| 106 | +``` |
| 107 | + |
| 108 | +5) User B pulls the merged changes from Remote Repository A to Local |
| 109 | + Repository A. |
| 110 | +```bash |
| 111 | +userb$ git checkout target-branch |
| 112 | +userb$ git pull upstream target-branch |
| 113 | +``` |
| 114 | + |
| 115 | +6) User B pushes the merged changes from Local Repository B to Remote |
| 116 | + Repository B. |
| 117 | +```bash |
| 118 | +userb$ git push origin target-branch |
| 119 | +``` |
| 120 | +If the original branch is not a permanent branch (i.e. the original branch is |
| 121 | +not the develop of master branch), then it should be removed. |
| 122 | +```bash |
| 123 | +userb$ git branch -d branch-name |
| 124 | +userb$ git push origin --delete branch-name |
| 125 | +``` |
| 126 | + |
| 127 | +### <a name="gitflow-workflow"></a> Gitflow Workflow |
| 128 | + |
| 129 | +The Gitflow Workflow is a set of rules that describe how branches, merges, and |
| 130 | +commits should be made. This project's micro workflow is based on the Gitflow |
| 131 | +Workflow described at |
| 132 | +[https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). |
| 133 | + |
| 134 | + |
| 135 | + |
| 136 | +In the Gitflow Workflow, there are two permanent branches: master and develop. |
| 137 | +All other branches have a limited lifespan and belong to one of three |
| 138 | +categories: features, fixes, and releases. |
| 139 | + |
| 140 | +* **master**: The master branch consists only of release commits (e.g. 1.0.0, |
| 141 | + 1.1.0, 1.2.1, etc). All commits are merges from a fix branch or a release |
| 142 | + branch. All commits are made by the repository maintainer. Contributors |
| 143 | + cannot commit to or merge into the master branch. |
| 144 | +* **develop**: The develop branch consists of development commits and merges |
| 145 | + from feature, fix, or release branches. Contributors should either branch |
| 146 | + from develop in order to work on a feature or commit changes to the develop |
| 147 | + branch in order to improve existing features. |
| 148 | +* **feature branches**: All feature branches must branch from the develop |
| 149 | + branch and merge into the develop branch. Feature branches may have any name. |
| 150 | + For this project, feature branches contain lowercase letters and dashes by |
| 151 | + convention. |
| 152 | +* **release branches**: All release branches must branch from the develop |
| 153 | + branch and merge into both the master branch and then the develop branch. |
| 154 | + Release branches are named "release-X.Y.0", where X and Y are integers and |
| 155 | + X.Y.0 is the upcoming release version. The project maintainer creates and |
| 156 | + merges release branches, and contributors may make commits to a release |
| 157 | + branch while it exists. Merges into a release branch generally are not |
| 158 | + allowed. |
| 159 | +* **fix branches**: All fix branches must branch from the master branch and |
| 160 | + merge into both the master branch and then the develop branch. Fix branches |
| 161 | + are named "fix-X.Y.Z", where X, Y, and Z are integers, X.Y is the current |
| 162 | + release version, and Z is the fix number. Fix branches are created to address |
| 163 | + pressing issues in the master branch code. Contributors may make commits to a |
| 164 | + fix branch while it exists, but merges into a fix branch are not allowed. |
| 165 | + |
| 166 | +The following example illustrates a contributor creating a feature branch. |
| 167 | +```bash |
| 168 | +userb$ git checkout -b feature-a develop |
| 169 | +``` |
| 170 | + |
| 171 | +Note that the Gitflow Workflow does not tolerate rebasing, cherry picking, |
| 172 | +forced pushes, or any other commands that corrupt the commit history. **It is |
| 173 | +the responsibility of the contributor to `git fetch` changes from upstream |
| 174 | +target branches and to `git merge --ff-only` these changes into local branches |
| 175 | +before making commits or submitting pull or merge requests.** |
| 176 | + |
| 177 | +## <a name="style-guide"></a> Style Guide |
| 178 | + |
| 179 | +Code should adhere to the following guidelines before being sumbitted through a |
| 180 | +pull or merge request. |
| 181 | + |
| 182 | +* Use two space characters instead of tab characters. Do not use tabs, and do |
| 183 | + not use four space characters for a tab. |
| 184 | +* The `{` character should always be preceded by a space character and, |
| 185 | + preceding the space character, the associated code. The `{` character should |
| 186 | + not be the first character of a line, and it should not be the first character |
| 187 | + of a line after excluding whitespace. |
| 188 | +* Text should be wrapped at 80 characters. |
| 189 | +* If wrapping a line of text, the new line of text should have the same amount |
| 190 | + of indentation as the wrapped line, plus one additional space character. E.g. |
| 191 | + do not inflate indentation to match an opening parenthesis on the wrapped |
| 192 | + line; instead, wrap the entire contents of the parentheses with the same |
| 193 | + indentation plus one additional space character. If wrapping a line multiple |
| 194 | + times, all wrapped lines have the same indentation as the first wrapped line. |
| 195 | + |
| 196 | +## <a name="license"></a> License |
| 197 | + |
| 198 | +Written by Bradley Denby |
| 199 | +Other contributors: None |
| 200 | + |
| 201 | +See the top-level LICENSE file for the license. |
0 commit comments