Merge changes I3ed7c0c9,Ie8a04df3,Ie844f5ac
* changes:
website: Fixed typos and awkward phrasing in Contributing guide
website: Updated contributing notes to show CI unit tests
website: Updated documentation for master-as-stable setup
diff --git a/_pages/contributing.md b/_pages/contributing.md
index 83fc93d..1a53bc3 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
@@ -75,7 +101,7 @@
* Function brackets must be on their own line.
* `for`/`if`/`while` branching operations must be followed by a white-space
before the conditional statement (e.g., `for (...)`).
-* `for`/`if`/`while` branching operations' opening bracket must be on on the
+* `for`/`if`/`while` branching operations' opening bracket must be on the
same line, with the closing bracket on its own line (e.g.,
`for (...) {\n ... \n}\n`). There should be a space between the condition(s)
and the opening bracket.
@@ -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
@@ -260,6 +286,7 @@
the change. At the time of writing, the continuous integration system will run:
```
+scons build/NULL/unittests.opt
cd tests
python main.py run
```
@@ -269,7 +296,7 @@
`-1` if it did not execute successfully.
Gerrit will permit a commit to be merged if at least one reviewer has given a
-`+2` to the "Reviewer" score; one maintainer has given a `+1` to the
+`+2` to the "Reviewer" score, one maintainer has given a `+1` to the
"Maintainer" score, and the continuous integration system has given a `+1` to
the "Verifier" score.
@@ -284,11 +311,9 @@
reviewers and contributors should be done in a polite manner. Rude and/or
dismissive remarks will not be tolerated.**
-When you understand what changes are required you should make your changes
-and upload them.
-
-Using the same workspace as before, make the necessary modifications to the
-gem5 repo, and amend the changes to the commit:
+When you understand what changes are required, using the same workspace as
+before, make the necessary modifications to the gem5 repo, and amend the
+changes to the commit:
```Shell
git commit --amend
@@ -297,7 +322,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 +345,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).
