process.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>cpp-netlib: Development Process</title>
    <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.0.2/css/bootstrap.min.css">
    <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.0.2/css/bootstrap-theme.min.css">
    <link rel="stylesheet" href="static/cpp-netlib.css">
  </head>
  <body data-spy="scroll" data-target="#cpp-netlib-docs-sidebar">
    <div id="wrap" class="row">
      <div class="container">
        <nav class="navbar navbar-fixed-top navbar-inverse cpp-netlib-navbar" role="navigation">
          <div class="container">
            <div class="navbar-header">
              <a class="navbar-brand" href="#">cpp-netlib</a>
            </div>
            <div>
            <ul class="nav navbar-nav">
              <li><a href="index.html">Home</a></li>
              <li class="active"><a href="process.html">Development Process</a></li>
              <li><a href="style-guide.html">Style Guide</a></li>
              <li><a href="proposals.html">Proposals</a></li>
            </ul>
            </div>
          </div>
        </nav>
        <header class="jumbotron subhead">
        <h1>Development Process</h1>
        <p class="lead">How we get things done.</p>
        </header>
        <div class="row">
          <div class="col-md-3" id="cpp-netlib-docs-sidebar" role="complimentary">
            <ul class="nav list-group cpp-netlib-sidebar" data-spy="affix" data-offset-top="245">
              <li class="list-group-item"><a href="#overview">Overview</a></li>
              <li class="list-group-item"><a href="#introduction">Introduction</a></li>
              <li class="list-group-item"><a href="#pull-requests">Pull Requests</a></li>
            </ul>
          </div>
          <div class="col-md-9">
            <section id="overview">
              <div class="page-header">
                <h1>Overview</h1>
              </div>
              <p>In this page we document the process by which the developers of
              the project collaborate and get things done. If you're interested
              in contributing or getting involved please consider the guidelines
              and tips that are outlined in this page. Please check-in often as
              we flesh out this document further.</p>
            </section>
            <section id="introduction">
              <div class="page-header">
                <h1>Introduction</h1>
              </div>
              <p>The first thing contributors and developers have to do is
              introduce themselves to the community. We'd like to have all
              contributors involved in the decision making process with regards
              to the development of both the community and the library. We value
              individuals and their personal styles, so the more everyone knows
              about everyone the better we can work together to achieve the same
              goal.</p>
              <p>If you haven't yet, please subscribe to the developers mailing
              list and introduce yourself before proceeding.</p>
              <p><a href="https://groups.google.com/group/cpp-netlib" class="btn btn-success" target="_blank">Subscribe</a></p>
            </section>
            <section id="pull-requests">
              <div class="page-header">
                <h1>Pull Requests</h1>
              </div>
              <p>The maintainers of the project review and merge <a
              href="https://help.github.com/articles/using-pull-requests"
              target="_blank">Pull Requests</a> (from here on out referred to
              as PR's) from contributors using the GitHub Pull Request feature.
              This allows the project to move forward using the Git distributed
              development workflow. If you need an introduction to git, please
              refer to the following links for git-specific information.</p>
              <ul>
              <li><a href="http://git-scm.com/book">ProGit</a> &mdash; a website 
              dedicated to basic and advanced git usage.</li>
              <li><a href="https://help.github.com/articles/set-up-git">GitHub 
              Git Setup</a> &mdash; the GitHub help pages on setting up git 
              to work with GitHub.</li>
              </ul>
              <p>What follows in this section assumes that you're already
              familiar with the basic git workflow.</p>
              <h2>Forking the Repo</h2>
              <p>Forking requires that you already have a GitHub account.
              Before continuing, please make sure that you've signed up for a
              GitHub account (it's free to develop for open source projects)
              and have familiarized yourself with the different development
              workflows. It's important that you understand the GitHub workflow
              before continuing.</p>
              <p>The official repository is located in GitHub at <a
              href="https://github.com/cpp-netlib/cpp-netlib"
              target="_blank">https://github.com/cpp-netlib/cpp-netlib</a>.
              Before you can submit PR's you should first create your own fork
              of the repository on GitHub. You can fork the repository by
              clicking on <a
              href="https://github.com/cpp-netlib/cpp-netlib/fork"
              class="btn btn-success" target="_blank">Fork</a> at the upper
              right portion of the page.</p>
              <h2>Preparing a PR</h2>
              <p>Once you have a fork of the repo, determine to which branch
              you'd like to send a PR to. In the next section we describe the
              various branches we'll be dealing with in the course of
              development of a release.</p>
              <p>When you've determined the branch to which you'd like to send
              a PR to you can follow these steps to prepare your change for
              inclusion in the library.</p>
              <ol>
              <li><strong>Create an integration branch.</strong> This
              integration branch should be rooted off the branch you intend to
              send a PR to. For example, if you're sending a PR to
              <code>cpp-netlib/master</code> and your fork is
              <code>user/master</code>, you should create a
              <code>user/master-integration</code> branch.</li>
              <li><strong>Create a topic branch.</strong> From the integration
              branch, you can then create as many topic branches as you want.
              It's recommended that you isolate all experimentation to branches
              &mdash; once you're resonably sure that your work is good to go,
              merge your topic branch into the integration branch in your local
              repo, then push the changes to your GitHub repo.</li>
              <li><strong>Make sure your integration branch is up to
              date.</strong> To do this you should first pull changes to your
              local master (assuming that's where you'd like to send a pull
              request to), rebase your integration branch to the tip of master,
              then make sure all merge conflicts are dealt with. Proceed only
              when your integration branch is up-to-date with the official
              branch you're going to send your PR to.</li>
              <li><strong>Send the PR.</strong> Once you're reasonably happy
              with the state of your integration branch, send off a PR to the
              official repo and set the destination branch as the branch you
              intend to send the change to.</li>
              <li><strong>Address Comments</strong> The maintainers will be
              reviewing your changes, and sometimes they may have comments they
              will ask you to address in your PR. You can do this by going back
              to the second step of this process, but you don't need to send
              another PR -- all you have to do is push your changes to your
              GitHub hosted integration branch and your PR will be updated
              automatically. That said, don't forget to update the discussion
              on the PR that you're ready for the PR to be reviewed again.</li>
              <li><strong>Your PR is merged.</strong> If you've done everything
              correctly up to this point, your PR should be cleanly merge-able
              into the branch you sent the PR to. A maintiner will merge you
              change into the project and you're now officially a contributor
              to the project!</li>
              </ol>
              <p>In case you have multiple PR's in flight, you may want to have
              multiple integration branches &mdash; that is, one integration
              branch per PR should be good to keep.</p>
              <h2>Working Branches</h2>
              <p>The project always has the latest bleeding edge versions of
              the library under development in the <code>master</code> branch.
              This version is explicitly unstable and subject to (potentially
              massive) changes over time.</p>
              <p>Once the state of <code>master</code> has stabilized and a
              release process is initiated by the project maintainers (it will
              be announced on the mailing list) a <code>version-devel</code>
              branch is started from master and a release candidate is
              prepared. For example, if a 1.0 release is initiated, a branch
              <code>1.0-devel</code> is started off master.</p>
              <p>A release candidate is tagged off of the
              <code>version-devel</code> branch on a regular basis, and is
              publicized as widely as possible. The tag name should be of the
              form <code>version-rcN</code>. Again as an example, the first
              release candidate for a 1.0 release will be tagged as
              <code>1.0.0-rc0</code>.</p>
              <p>All PR's for the upcoming version should go directly to the
              <code>version-devel</code> branch.</p>
              <p>During the stabilization of the <code>version-devel</code>
              branch, master remains open for PR's for new functionality, new
              accepted libraries, and API breaking changes.</p>
              <p>Once a release candidate is deemed "good to go" by the
              maintainers we tag the library (and submodules appropriately)
              with a tag of the form <code>version-final</code>. As with
              earlier examples, the tag for the 1.0 release would be
              <code>1.0.0-final</code>.</p>
              <h3>Patch Releases</h3>
              <p>Critical bug fixes go into the <code>version-devel</code>
              branch after a final release has been packaged. In case there's a
              need for update releases, the release candidate process is
              followed until another final version of the patch release is
              tagged.</p>
              <p>In our on-going example, this will be of the form
              <code>1.0.1-rc0</code>, <code>1.0.1-rc1</code>, and so on until
              it's stabilized &mdash; at which time a <code>1.0.1-final</code>
              is tagged and packaged.</p>
            </section>
          </div>
        </div>
      </div>
    </div>
    <footer id="footer">
      <div class="container">
        <p class="muted credit">Copyright 2012 Dean Michael Berris; Glyn
        Matthews; Google, Inc.</p>
        <p class="muted credit">Distributed under the Boost Software License,
        Version 1.0. (See accompanying file <a
        href="LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a
        href="//www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
      </div>
    </footer>
    <script src="//code.jquery.com/jquery-3.7.1.slim.min.js"></script>
    <script src="//netdna.bootstrapcdn.com/bootstrap/3.0.2/js/bootstrap.min.js"></script>
    <script type="text/javascript">
      var _gaq = _gaq || [];
      _gaq.push(['_setAccount', 'UA-19815738-1']);
      _gaq.push(['_trackPageview']);

      (function() {
       var ga = document.createElement('script'); ga.type =
       'text/javascript'; ga.async = true;
       ga.src = ('https:' == document.location.protocol ?
         'https://ssl' : 'http://www') +
       '.google-analytics.com/ga.js';
       var s = document.getElementsByTagName('script')[0];
       s.parentNode.insertBefore(ga, s);
       })();
     </script>
  </body>
</html>