Initial version of the branching strategy docs.

Author: griwes

doc/branching.md

@@ -0,0 +1,123 @@
+# Thrust Branching and Development Model
+
+The following is a description of how the Thrust development teams approaches branching and release tagging. This
+is a living document that will evolve as our process evolves.
+
+## Thrust Version
+
+Thrust has historically had its own versioning system, independent of the versioning scheme of the CUDA Toolkit.
+Today, Thrust is released with the CUDA Toolkit, but we currently still maintain the double versioning scheme.
+
+The following is a mapping from Thrust versions to CUDA Toolkit versions and vice versa. Note that some Thrust
+versions don't directly map to any CUDA Toolkit version.
+
+| Thrust version    | CUDA version  |
+| ----------------- | ------------- |
+| v1.9.4            | 10.1          |
+| v1.9.3            | 10.0          |
+| v1.9.2            | 9.2           |
+| v1.9.1-2          | 9.1           |
+| v1.9.0-4          | 9.0           |
+| v1.8.3-2          | 8.0           |
+| v1.8.2            | 7.0           |
+| v1.8.1            | 7.0           |
+| v1.8.0            | N/A           |
+| v1.7.2            | 6.5           |
+| v1.7.1            | 6.0           |
+| v1.7.0            | 5.5           |
+| v1.6.0            | N/A           |
+| v1.5.3            | 5.0           |
+| v1.5.2            | 4.2           |
+| v1.5.1            | 4.1           |
+| v1.5.0            | N/A           |
+| v1.4.0            | 4.0           |
+| v1.3.0            | 3.2           |
+| v1.2.1            | 3.1           |
+| v1.2.0            | N/A           |
+| v1.1.1            | N/A           |
+| v1.1.0            | N/A           |
+| v1.0.0            | N/A           |
+
+## Repositories
+
+As Thrust is developed both on GitHub and internally at NVIDIA, there's three main places where code lives:
+
+  * The [public Thrust repository](https://github.com/thrust/thrust), referred to as `github` later in this
+    document.
+  * An internal GitLab repository, referred to as `gitlab` later in this document.
+  * An internal Perforce repository, referred to as `perforce` later in this document.
+
+## Branches and Tags
+
+The following tag names are used in the Thrust project:
+
+  * `github/cuda-X.Y`: the tag that directly corresponds to what has been shipped in the CUDA Toolkit release X.Y.
+  * `github/vA.B.C`: the tag that directly corresponds to a Thrust version A.B.C.
+
+The following branch names are used in the Thrust project:
+
+  * `github/master`: the Source of Truth development branch of Thrust.
+  * `github/old-master`: the old Source of Truth branch, before unification of public and internal repositories.
+  * `perforce/private`: mirrored github/master, plus files necessary for internal NVIDIA testing systems.
+  * `gitlab/staging/cuda-X.Y`: the branch for a CUDA Toolkit release that has not been released yet. cuda-X.Y should
+    be tagged on this branch after the final commit freeze (see "Release branches" below).
+  * `github/maintenance/cuda-Z.W`: the continuation of gitlab/staging/cuda-Z.W, but after release of CUDA Z.W, plus
+    post-release fixes if any are needed (see "Old release branches" below).
+  * `gitlab/feature/<name>`: feature branch for internally developed features.
+  * `gitlab/bug/<bug-system><bug-name>`: bug fix branch.
+  * `gitlab/master`: same as `github/master`, but not yet published, during a freezing period (see "Feature freeze"
+    below).
+
+## Development Process Described
+
+### Normal development
+
+During regular parts of the development cycle, when we develop features on feature branches, and fix bugs on the
+main branch, we can:
+
+  1. Merge internal fixes to `github/master` and to `perforce/private`.
+  2. Merge Github contributions to `github/master` and to `perforce/private`.
+
+### Feature freeze
+
+In case where we have a new feature for a CUDA Toolkit release: just before the CUDA Toolkit feature freeze for a
+new release branch, we should stop merging commits (including public contributions) to `github/master`, and move to
+development on `gitlab/master`, and merge the not yet public features there.
+
+In those cases, we should wait until the new version of the toolkit is released before we push the new updated
+`gitlab/master` to `github/master`, roughly at the same time as we push from `gitlab/staging/cuda-X.Y` to
+`github/maintenance/cuda-X.Y` and tag `cuda-X.Y`, and the appropriate Thrust version tag.
+
+If we don't have big, not-public-before-release features landing in X.Y, however, we can avoid having a feature
+freeze period.
+
+The reason for having a freeze period at all is: `github/master` is supposed to be the Source of Truth. We want the
+history to follow the same order of commits in both Git and Perforce, and once a change is merged, we cannot rebase
+things that went into `perforce/internal` on top of it. Therefore: since we only really commit to Perforce but not
+`github/master` when we have a feature that is ready to be delivered, but is only a part of a new release and
+shouldn't/can't be public yet, we have to make sure that after it is merged to `gitlab/master` (and to `perforce/internal`),
+nothing new lands in `github/master` before we push the feature out.
+
+To avoid situations like this with bug fixes, when we fix a bug at a not crazy point in the release cycle, we
+should develop it on git, merge/push it on Github, and then pull the new commit to Perforce.
+
+### Release branches
+
+These are the internal Git branches that map directly to internal CUDA release branches. These branches are primarily
+developed in Git, and commits applied to them are then pushed to Perforce.
+
+After a CUDA Toolkit version is released, these transition to being old release branches.
+
+### Old release branches
+
+These branches represent a version that has landed in a CUDA Toolkit version, but with bugfixes for things that do
+deserve being fixed on a release branch. These shouldn't be groundbreaking; the following are an acceptable set of
+fixes to go into these branches, because they can remove annoyances, but shouldn't change behavior:
+
+  * Documentation fixes and updates.
+  * Thrust build system changes.
+  * Additional examples, fixes to examples and tests.
+  * (Possibly:) Fixing missing headers. This one is slightly less obvious, because it makes it possible for users
+    of standalone Thrust to write programs that won't compile with CUDA Thrust. Determinations will be made on a
+    case by case basis.
+