|
| 1 | +Overview |
| 2 | +======== |
| 3 | + |
| 4 | +In this page we document the process by which the developers of the |
| 5 | +project collaborate and get things done. If you're interested in |
| 6 | +contributing or getting involved please consider the guidelines and |
| 7 | +tips that are outlined in this page. Please check-in often as we flesh |
| 8 | +out this document further. |
| 9 | + |
| 10 | +Introduction |
| 11 | +============ |
| 12 | + |
| 13 | +The first thing contributors and developers have to do is introduce |
| 14 | +themselves to the community. We'd like to have all contributors |
| 15 | +involved in the decision making process with regards to the |
| 16 | +development of both the community and the library. We value |
| 17 | +individuals and their personal styles, so the more everyone knows |
| 18 | +about everyone the better we can work together to achieve the same |
| 19 | +goal. |
| 20 | + |
| 21 | +If you haven't yet, please `subscribe`_ to the developers mailing list |
| 22 | +and introduce yourself before proceeding. |
| 23 | + |
| 24 | +.. _`subscribe`:https://groups.google.com/group/cpp-netlib` |
| 25 | + |
| 26 | +Pull Requests |
| 27 | +============= |
| 28 | + |
| 29 | +The maintainers of the project review and merge `Pull Requests`_ (from |
| 30 | +here on out referred to as PR's) from contributors using the GitHub |
| 31 | +Pull Request feature. This allows the project to move forward using |
| 32 | +the Git distributed development workflow. If you need an introduction |
| 33 | +to git, please refer to the following links for git-specific |
| 34 | +information. |
| 35 | + |
| 36 | +.. _`Pull Requests`:https://help.github.com/articles/using-pull-requests |
| 37 | + |
| 38 | +* `ProGit`_ — a website dedicated to basic and advanced git usage. |
| 39 | +* `GitHub Git Setup`_ — the GitHub help pages on setting up git to work |
| 40 | + with GitHub. |
| 41 | + |
| 42 | +.. _`ProGit`:http://git-scm.com/book |
| 43 | +.. _`GitHub Git Setup`:https://help.github.com/articles/set-up-git |
| 44 | + |
| 45 | +What follows in this section assumes that you're already familiar with |
| 46 | +the basic git workflow. |
| 47 | + |
| 48 | +Forking the Repo |
| 49 | +================ |
| 50 | + |
| 51 | +Forking requires that you already have a GitHub account. Before |
| 52 | +continuing, please make sure that you've signed up for a GitHub |
| 53 | +account (it's free to develop for open source projects) and have |
| 54 | +familiarized yourself with the different development workflows. It's |
| 55 | +important that you understand the GitHub workflow before continuing. |
| 56 | + |
| 57 | +The official repository is located in GitHub at |
| 58 | +https://github.com/cpp-netlib/cpp-netlib. Before you can submit PR's |
| 59 | +you should first create your own fork of the repository on GitHub. You |
| 60 | +can fork the repository by clicking on `Fork`_ at the upper right portion |
| 61 | +of the page. |
| 62 | + |
| 63 | +.. _`Fork`:https://github.com/cpp-netlib/cpp-netlib/fork |
| 64 | + |
| 65 | +Preparing a PR |
| 66 | +============== |
| 67 | + |
| 68 | +Once you have a fork of the repo, determine to which branch you'd like |
| 69 | +to send a PR to. In the next section we describe the various branches |
| 70 | +we'll be dealing with in the course of development of a release. |
| 71 | + |
| 72 | +When you've determined the branch to which you'd like to send a PR to |
| 73 | +you can follow these steps to prepare your change for inclusion in the |
| 74 | +library. |
| 75 | + |
| 76 | +# Create an integration branch. This integration branch should be |
| 77 | + rooted off the branch you intend to send a PR to. For example, if |
| 78 | + you're sending a PR to cpp-netlib/master and your fork is |
| 79 | + user/master, you should create a user/master-integration branch. |
| 80 | + |
| 81 | +# Create a topic branch. From the integration branch, you can then |
| 82 | + create as many topic branches as you want. It's recommended that you |
| 83 | + isolate all experimentation to branches — once you're resonably sure |
| 84 | + that your work is good to go, merge your topic branch into the |
| 85 | + integration branch in your local repo, then push the changes to your |
| 86 | + GitHub repo. |
| 87 | + |
| 88 | +# Make sure your integration branch is up to date. To do this you |
| 89 | + should first pull changes to your local master (assuming that's where |
| 90 | + you'd like to send a pull request to), rebase your integration branch |
| 91 | + to the tip of master, then make sure all merge conflicts are dealt |
| 92 | + with. Proceed only when your integration branch is up-to-date with the |
| 93 | + official branch you're going to send your PR to. |
| 94 | + |
| 95 | +# Send the PR. Once you're reasonably happy with the state of your |
| 96 | + integration branch, send off a PR to the official repo and set the |
| 97 | + destination branch as the branch you intend to send the change to. |
| 98 | + |
| 99 | +# Address Comments The maintainers will be reviewing your changes, and |
| 100 | + sometimes they may have comments they will ask you to address in |
| 101 | + your PR. You can do this by going back to the second step of this |
| 102 | + process, but you don't need to send another PR -- all you have to do |
| 103 | + is push your changes to your GitHub hosted integration branch and |
| 104 | + your PR will be updated automatically. That said, don't forget to |
| 105 | + update the discussion on the PR that you're ready for the PR to be |
| 106 | + reviewed again. |
| 107 | + |
| 108 | +# Your PR is merged. If you've done everything correctly up to this |
| 109 | + point, your PR should be cleanly merge-able into the branch you sent |
| 110 | + the PR to. A maintiner will merge you change into the project and |
| 111 | + you're now officially a contributor to the project! |
| 112 | + |
| 113 | + |
| 114 | +In case you have multiple PR's in flight, you may want to have |
| 115 | +multiple integration branches — that is, one integration branch per PR |
| 116 | +should be good to keep. |
| 117 | + |
| 118 | +Working Branches |
| 119 | +================ |
| 120 | + |
| 121 | +The project always has the latest bleeding edge versions of the |
| 122 | +library under development in the master branch. This version is |
| 123 | +explicitly unstable and subject to (potentially massive) changes over |
| 124 | +time. |
| 125 | + |
| 126 | +Once the state of master has stabilized and a release process is |
| 127 | +initiated by the project maintainers (it will be announced on the |
| 128 | +mailing list) a version-devel branch is started from master and a |
| 129 | +release candidate is prepared. For example, if a 1.0 release is |
| 130 | +initiated, a branch 1.0-devel is started off master. |
| 131 | + |
| 132 | +A release candidate is tagged off of the version-devel branch on a |
| 133 | +regular basis, and is publicized as widely as possible. The tag name |
| 134 | +should be of the form version-rcN. Again as an example, the first |
| 135 | +release candidate for a 1.0 release will be tagged as 1.0.0-rc0. |
| 136 | + |
| 137 | +All PR's for the upcoming version should go directly to the |
| 138 | +version-devel branch. |
| 139 | + |
| 140 | +During the stabilization of the version-devel branch, master remains |
| 141 | +open for PR's for new functionality, new accepted libraries, and API |
| 142 | +breaking changes. |
| 143 | + |
| 144 | +Once a release candidate is deemed "good to go" by the maintainers we |
| 145 | +tag the library (and submodules appropriately) with a tag of the form |
| 146 | +version-final. As with earlier examples, the tag for the 1.0 release |
| 147 | +would be 1.0.0-final. |
| 148 | + |
| 149 | +Patch Releases |
| 150 | +============== |
| 151 | + |
| 152 | +Critical bug fixes go into the version-devel branch after a final |
| 153 | +release has been packaged. In case there's a need for update releases, |
| 154 | +the release candidate process is followed until another final version |
| 155 | +of the patch release is tagged. |
| 156 | + |
| 157 | +In our on-going example, this will be of the form 1.0.1-rc0, |
| 158 | +1.0.1-rc1, and so on until it's stabilized — at which time a |
| 159 | +1.0.1-final is tagged and packaged. |