Initial version of the branching strategy docs.
ADD
doc/branching.md
+# 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.
+

Initial version of the branching strategy docs.