website: Updated documentation for master-as-stable setup
Change-Id: Ie844f5acd57e3b89ed04f7fc7d831f6ab0b620eb
diff --git a/_pages/contributing.md b/_pages/contributing.md
index 83fc93d..292450d 100644
--- a/_pages/contributing.md
+++ b/_pages/contributing.md
@@ -48,8 +48,34 @@
git clone https://gem5.googlesource.com/public/gem5
```
-This local repo can then be modified to incorporate the task you have assigned
-yourself.
+### master-as-stable / develop branch
+
+By default, the git repo will have the `master` branch checked-out. The
+`master` branch is considered the gem5 stable release branch. I.e., the HEAD
+of this branch contains the latest stable release of gem5. (execute `git tag`
+on the `master` branch to see the list of stable releases. A particular
+release may be checked out by executing `git checkout <release>`). As the
+`master` branch only contains officially released gem5 code **contributors
+should not develop changes on top of the `master` branch** they should instead
+**develop changes on top of the `develop` branch**.
+
+To checkout the `develop` branch:
+
+```Shell
+git checkout --track origin/develop
+```
+
+Changes may be made on this branch to incorporate changes assigned to yourself.
+
+As the develop branch is frequently updated, regularly obtain the latest
+`develop` branch by executing:
+
+```
+git pull --rebase
+```
+
+Conflicts may need resolved between your local changes and new changes on the
+`develop` branch.
## Making modifications
@@ -212,7 +238,7 @@
To start this process, execute:
```
-git push origin HEAD:refs/for/master
+git push origin HEAD:refs/for/develop
```
At this stage you may receive an error if you're not registered to contribute
@@ -297,7 +323,7 @@
Then push the new changes to Gerrit:
```Shell
-git push original HEAD:refs/for/master
+git push original HEAD:refs/for/develop
```
If for some reason you no longer have your original workspace, you may pull
@@ -320,3 +346,7 @@
As one last step, you should change the corresponding Jira issue status to
`Done` then link the Gerrit page as a comment on Jira as to provide evidence
that the task has been completed.
+
+Stable releases of gem5 are published three times per year. Therefore, a change
+successfully submitted to the `develop` branch will be merged into the `master`
+branch within three to four months after submission.
diff --git a/_pages/getting_started.md b/_pages/getting_started.md
index 1361c25..46e7d0e 100644
--- a/_pages/getting_started.md
+++ b/_pages/getting_started.md
@@ -59,9 +59,23 @@
### What version of gem5 should I use?
-For now, the best version of gem5 to use is the most recent.
-Very soon, we will be creating a stable release channel for gem5.
-Until then, simply use the master branch on our Git repository.
+The gem5 git repository has two branches: `develop` and `master`. The `develop`
+branch contains the very latest gem5 changes **but is not stable**. It is
+frequently updated. **The `develop` branch should only be used when
+contributing the the gem5 project** (please see our [Contributing Guide](
+/contributing) for more information on how to submit code to gem5).
+
+The master branch contains stable gem5 code. The HEAD of the master branch
+points towards the latest gem5 release. We would advise researchers use the
+latest stable release of gem5 and report which version was used when publishing
+results (use `git describe` to see latest gem5 release version number).
+
+If replicating previous work, please find which version of gem5 was used. This
+version should be tagged on the `master` branch and can thereby be checked-out
+on a new branch using `git checkout -b {branch} {version}`.
+E.g., to checkout `v19.0.0` on a new branch called `version19`:
+`git checkout -b version19 v19.0.0`. A complete list of released gem5
+versions can be determined by executing `git tag` on the `master` branch.
### How should I cite gem5?
@@ -92,4 +106,4 @@
- [All logos (svg)](/assets/img/gem5logo/gem5masterFile.svg)
Please follow the [gem5 logo style guide](/assets/img/gem5logo/gem5styleguide.pdf) when using the gem5 logo.
-More details and more versions of the logo can be found in [the source for gem5's documentation](https://github.com/gem5/new-website/tree/master/assets/img/gem5logo).
\ No newline at end of file
+More details and more versions of the logo can be found in [the source for gem5's documentation](https://github.com/gem5/new-website/tree/master/assets/img/gem5logo).
