<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>