diff --git a/.gitignore b/.gitignore index 77ea6d970..9882043bd 100644 --- a/.gitignore +++ b/.gitignore @@ -10,4 +10,4 @@ _site/ # For Mac and images .DS_Store -.venv +.venv \ No newline at end of file diff --git a/README.md b/README.md index 5e466960f..84cb3a801 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,8 @@ You may clone the repository, and run a local instance of the website using: ``` -git clone https://github.com/gem5/website.git -cd website +git clone https://github.com/gem5/website +cd gem5-website bundle jekyll serve --config _config.yml,_config_dev.yml ``` @@ -61,35 +61,39 @@ Jira: https://gem5.atlassian.net/browse/GEM5-186 ## Submitting a contribution -We utilize Gerrit to review changes made to the website. Once changes are -committed to a local repository they may be submitted for review by executing: +We utilize GitHub to review changes made to the website. To make +changes, follow the steps below. + +1. Fork the gem5 repository on GitHub from https://github.com/gem5/gem5-website/. +2. Create a new branch in your forked repository for your changes. +3. Commit your changes to the new branch. +4. Push the branch to your forked repository. +5. Open a pull request from your branch in your forked repository to the main gem5 website repository. -``` -git push origin HEAD:refs/for/stable -``` -At this stage you may receive an error if you're not registered to contribute -to our Gerrit. To resolve this issue: +If you have not signed up for an account on the github +(https://github.com/), you first have to create an account. -1. Create an account at https://gem5-review.googlesource.com -2. Go to `User Settings` -3. Select `Obtain password` (under `HTTP Credentials`). -4. A new tab shall open, explaining how to authenticate your machine to make -contributions to Gerrit. Follow these instructions and try pushing again. + 1. Go to https://github.com/ + 2. Click "Sign up" in the upper right corner. -Gerrit will amend your commit message with a `Change-ID`. Any commit pushed to -Gerrit with this Change-ID is assumed to be part of this change. +Changes are required to have a `Change-ID`, whic can be added using the pre-commit +hook. This can be installed via the following: + +``` bash +pip install pre-commit +pre-commit install +``` ### Code Review -Once a change has been submitted to Gerrit, you may view the change at - under `Your` -> `Changes` -> -`Outgoing reviews`). +Once a change has been submitted to GitHub, you may view the change at +. -Through the Gerrit prowl we strongly advise you add reviewers to your change. -Gerrit will automatically notify those you assign. We recommend you add both -**Bobby R. Bruce ** and **Jason Lowe-Power -** as reviewers. +Through the GitHub pull request we strongly advise you add reviewers to your change. +GitHub will automatically notify those you assign. We recommend you add both +**Bobby R. Bruce ** (@BobbyRBruce) and **Jason Lowe-Power +** (@powerjg) as reviewers. Reviewers will review the change. For non-trivial edits, it is not unusual for a change to receive feedback from reviewers that they want incorporated @@ -97,8 +101,7 @@ before flagging as acceptable for merging into the gem5 website repository. **All communications between reviewers and contributors should be done in a polite manner. Rude and/or dismissive remarks will not be tolerated**. -Once your change has been accepted by reviewers you will be able to click -`Submit` within your changes Gerrit page. This focally merges the change +Once your change has been accepted by reviewers a maintainer will squash and merge your pull request into the gem5 website repository. into the gem5 website repository. The website will be automatically updated with your changes within 30 minutes. diff --git a/_data/documentation.yml b/_data/documentation.yml index 37958eec3..b117d76ea 100755 --- a/_data/documentation.yml +++ b/_data/documentation.yml @@ -68,6 +68,10 @@ docs: url: http://doxygen.gem5.org/release/v22-0-0-1/index.html - page: v22.1.0.0 url: http://doxygen.gem5.org/release/v22-1-0-0/index.html + - page: v23.0.0.0 + url: http://doxygen.gem5.org/release/v23-0-0-0/index.html + - page: v23.0.0.1 + url: http://doxygen.gem5.org/release/v23-0-0-1/index.html - title: gem5 standard library id: gem5-standard-library diff --git a/_pages/contributing.md b/_pages/contributing.md index d2a87d7fb..65b35f016 100644 --- a/_pages/contributing.md +++ b/_pages/contributing.md @@ -16,24 +16,23 @@ to the gem5 project. ## Determining what you can contribute The easiest way to see how you can contribute to gem5 is to check our Jira -issue tracker: . From Jira you can check open -issues. +issue tracker: or GitHub issue tracker: +. Browse these open issues and see if there are any which you are capable of handling. When you find a task you are happy to carry out, verify no one else is presently assigned, then leave a comment asking if you may assign yourself -this task (this will involve creating a Jira account). Though not mandatory, we +this task. Though not mandatory, we advise first-time contributors do this so developers more familiar with the task may give advice on how best to implement the necessary changes. Once a developers has replied to your comment (and given any advice they may -have), you may officially assign yourself the task. After this you should -change the status of the task from `Todo` to `In progress`. This helps the gem5 +have), you may officially assign yourself the task. This helps the gem5 development community understand which parts of the project are presently being worked on. **If, for whatever reason, you stop working on a task, please unassign -yourself from the task and change the task's status back to `Todo`.** +yourself from the task.** ## Obtaining the git repo @@ -44,13 +43,28 @@ exclusively.** To pull the gem5 git repo: -```Shell +```sh git clone https://github.com/gem5/gem5 ``` +If you wish to use gem5 and never contribute, this is fine. However, to +contribute, we use the [GitHub Pull-Request model](https://docs.github.com/en/pull-requests), and therefore recommend [Forking the gem5 repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) prior to contributing. + +### Forking + +Please consult the [GitHub documentation on Forking a GitHub repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo). +As we will be working atop the `develop` branch, please ensure you Fork all the repository's branches, not just the `stable` branch. + +This will create your own forked version of the gem5 repo on your own GitHub account. +You may then obtain it locally using: + +```sh +git clone https://github.com/{your github account}/gem5 +``` + ### stable / develop branch -By default, the git repo will have the `stable` branch checked-out. The +When cloned the git repo will have the `stable` branch checked-out by default. The `stable` branch is the gem5 stable release branch. I.e., the HEAD of this branch contains the latest stable release of gem5. (execute `git tag` on the `stable` branch to see the list of stable releases. A particular @@ -59,23 +73,23 @@ release may be checked out by executing `git checkout `). As the should not develop changes on top of the `stable` branch** they should instead **develop changes on top of the `develop` branch**. -To checkout the `develop` branch: +To switch to the `develop` branch: -```Shell -git checkout --track origin/develop +```sh +git switch develop ``` -Changes may be made on this branch to incorporate changes assigned to yourself. +The develop `branch` is merged into the `stable` branch upon a gem5 release. +Therefore, any changes you make exist on the develop branch until the next release. -As the develop branch is frequently updated, regularly obtain the latest -`develop` branch by executing: +We strongly recommend creating your own local branches to do changes. +The flow of development works best if `develop` and `stable` are not modified directly. +This helps keep your changes organized across different branches in your forked repository. +The following example will create a new branch, from `develop`, called `new-feature`: +```sh +git switch -c new-feature ``` -git pull --rebase -``` - -Conflicts may need resolved between your local changes and new changes on the -`develop` branch. ## Making modifications @@ -156,7 +170,7 @@ Then run on modified/added python files using: black ``` -For varibale/method/etc. naming conventions, please follow the [PEP 8 naming +For variable/method/etc. naming conventions, please follow the [PEP 8 naming convention recommendations]( https://peps.python.org/pep-0008/#naming-conventions). While we try our best to enforce naming conventions across the gem5 project, we are aware there are @@ -178,29 +192,26 @@ pre-commit install ``` Once installed pre-commit will run checks on modified code prior to running the -`git commit` command (see [our section on commiting](#committing) for more -details on commiting your changes). If these tests fail you will not be able to +`git commit` command (see [our section on committing](#committing) for more +details on committing your changes). If these tests fail you will not be able to commit. -These same pre-commit checks are run as part of Gerrit's CI checks (those -which must pass to obtain a "Verified" status required for a change to be -incorporated into the develop branch). It is therefore recommended that -developers install pre-commit to catch style errors early. - -**Note:** As of the v22.0 release, the pre-commit hook is only available on the -develop branch. +These same pre-commit checks are run as part our CI checks (those +which must pass in order for a change to be merged into the develop branch). It +is therefore strongly recommended that developers install pre-commit to catch +style errors early. ## Compiling and running tests The minimum criteria for a change to be submitted is that the code is compilable and the test cases pass. -The following command both compiles the project and runs our system-level -checks: +The following command both compiles the project and runs our "quick" +system-level checks: -```Shell +```sh cd tests -python main.py run +./main.py run ``` **Note: These tests can take several hours to build and execute. `main.py` may @@ -209,22 +220,19 @@ be run on multiple threads with the `-j` flag. E.g.: `python main.py run The unit tests should also pass. To run the unit tests: -```Shell +```sh scons build/NULL/unittests.opt ``` To compile an individual gem5 binary: -```Shell -scons build/{ISA}/gem5.opt +```sh +scons build/ALL/gem5.opt ``` -where `{ISA}` is the target ISA. Common ISAs are `ARM`, `MIPS`, `POWER`, -`RISCV`, `SPARC`, and `X86`. So, to build gem5 for `X86`: - -```Shell -scons build/X86/gem5.opt -``` +This compiles a gem5 binary containing "ALL" ISA targets. For more information +on building gem5 please consult our [building documentation]( +/documentation/general_docs/building). ## Committing @@ -235,6 +243,7 @@ files: git add ``` +Make sure these changes are being added to your forked repository. Then commit using: ```Shell @@ -275,136 +284,81 @@ Jira Issue: https://gem5.atlassian.net/browse/GEM5-186 If you feel the need to change your commit, add the necessary files then _amend_ the changes to the commit using: -``` +```sh git commit --amend ``` This will give you opportunity to edit the commit message. -## Pushing to Gerrit +You may continue to add more commits as a chain of commits to be included in the pull-request. +However, we recommend that pull-requests are kept small and focused. +For example, if you wish to add a different feature or fix a different bug, we recommend doing so in another pull requests. -Pushing to Gerrit will allow others in the gem5 project to review the change to -be fully merged into the gem5 source. +## Keeping your forked and local repositories up-to-date -To start this process, execute: +While working on your contribution, we recommend keeping your forked repository in-sync with the source gem5 repository. +To do so, regularly [Sync your fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork). +This can be done via the GitHub web interface and, if so, you should `git pull` on top of your local `stable` and `develop` branches to ensure your local repository is in-sync. +To do so from the command line: +```sh +# Add the main gem5 repository as a remote on your local repository. This only +# needs done once. +git remote add upstream https://github.com/gem5/website.git + +git fetch upstream # Obtain the latest from the gem5 repo. +git switch develop # Switch to the develop branch. +git merge upstream/develop # Merge the latest changes into the develop branch. +git push # Push to develop to your forked repo. +git switch stable # Switch to the stable branch. +git merge upstream/stable # Merge the latest changes into the stable branch. +git push # Push the changes to stable to your forked repo. ``` -git push origin HEAD:refs/for/develop -``` - -At this stage you may receive an error if you're not registered to contribute -to our Gerrit. To resolve this issue: - -1. Create an account at . -2. Go to `User Settings`. -3. Select `Obtain password` (under `HTTP Credentials`). -4. A new tab shall open, explaining how to authenticate your machine to make -contributions to Gerrit. Follow these instructions and try pushing again. - -Gerrit will amend your commit message with a `Change-ID`. Any commit pushed -to Gerrit with this `Change-ID` is assumed to be part of this change. -## Code review +As our local branch work atop the `develop` branch, once we've synced our forked repository, we can rebase our local branch on top of the `develop` branch. +Assuming our local branch is called `new-feature`: -Now, at , you can view the -change you have submitted (`Your` -> `Changes` -> `Outgoing reviews`). We -suggest that, at this stage, you mark the corresponding Jira issue -as `In Review`. Adding a link to the change on Gerrit as a comment to the -issue is also helpful. +```sh +git switch develop # Switching back to the develop branch. +git pull # Ensuring we have the latest from the forked repository. +git switch new-feature # Switching back to our local branch. +git rebase develop # Rebasing our local branch on top of the develop branch. +``` -Through the Gerrit portal we strongly advise you add reviewers. -Gerrit will automatically notify those you assign. The "maintainers" of the -components you have modified should be added as reviewers. These should -correspond to the tags you included in the commit header. **Please consult -[MAINTAINERS.yaml]( -https://github.com/gem5/gem5/blob/stable/MAINTAINERS.yaml) to -see who maintains which component**. As an example, for a commit with a header -of `tests,arch : This is testing the arch component` then the maintainers for -both `tests` and `arch` should be included as reviewers. +Conflicts may need resolved between your branch and new changes. -Reviewers will then review this change. There are three scores which the commit -shall be evaluated: "Code-Review", "Maintainer", and "Verified". +## Pushing and creating a pull request -Each reviewer can give a score from `-2` to `+2` to the "Code-Review" score, -where `+2` indicates the reviewer is 100% okay with the patch in its current -state and `-2` when the reviewer is certain they do not want the patch -merged in its current state. +Once you have completed your changes locally, you can push to your forked gem5 repository. +Assuming the branch we are working on is `new-feature`: -Maintainers can add `+1` or `-1` to the "Maintainer" score. A `+1` score -indicates that the maintainer is okay with the patch. +```sh +git switch new-feature # Ensure we are on the 'new-feature' branch. +git push --set-upstream origin new-feature +``` -When a Maintainer gives a `+1` our continuous integration system will process -the change. At the time of writing, the continuous integration system will run: +Now, via the GitHub web interface, you can [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) of your changes from your forked repository's branch into the gem5 `develop` branch. -``` -scons build/NULL/unittests.opt -cd tests -python main.py run -``` +## Passing the checks -If this executes successfully (i.e. the project builds and the tests pass) the -continuous integration system will give a `+1` to the "Verifier" score, and a -`-1` if it did not execute successfully. +Once you have created a pull request, the gem5 Continuous Integration (CI) tests will run. +These run a series of checks to ensure your changes are valid. +These must pass before your changes can be merged into the gem5 `develop` branch. -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 -"Maintainer" score, and the continuous integration system has given a `+1` to -the "Verifier" score. +In addition to the CI tests, your changes will be reviewed by the gem5 community. +Your pull-request must have the approval of at least one community member prior to being merged. -For non-trivial changes, it is not unusual for a change to receive feedback -from reviewers that they will want incorporated before giving the commit a -score necessary for it to be merged. This leads to an iterative process. +Once your pull-request has passed all the CI tests and has been approved by at least one community member, it will be merged a gem5 Project Maintainer will do a [Squash and Merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits) on the pull-request. ### Making iterative improvements based on feedback -A reviewer will ask questions and post suggestions on Gerrit. You should read +A reviewer will ask questions and post suggestions on GitHub. You should read these comments and answer these questions. **All communications between 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, 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 -``` - -Then push the new changes to Gerrit: - -```Shell -git push origin HEAD:refs/for/develop -``` - -If for some reason you no longer have your original workspace, you may pull -the change by going to your change in Gerrit, clicking `Download` and executing -one of the listed commands. - -When your new change is uploaded via the `git push` command, the reviewers will -re-review the change to ensure you have incorporated their suggested -improvements. The reviewers may suggest more improvements and, in this case, -you will have to incorporate them using the same process as above. **This -process is therefore iterative, and it may therefore take several cycles until -the patch is in a state in which the reviewers are happy**. Please do not -be deterred, it is very common for a change to require several iterations. - -## Submit and merge - -Once this iterative process is complete. The patch may be merged. This is done -via Gerrit (Simply click `Submit` within the relevant Gerrit page). - -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 `stable` -branch within three to four months after submission. - -## gem5 Bootcamp 2022 +When you understand what changes are required make amendments to the pull +request by adding patches to the same branch and then pushing to the forked repository. -As part of [gem5's 2022 Bootcamp](/events/boot-camp-2022), contributing to gem5 -was taught as a tutorial. Slides for this tutorial can be found [here]( -https://ucdavis365-my.sharepoint.com/:p:/g/personal/jlowepower_ucdavis_edu/EQLtRAKI94JKjgk5pBmJtG8B3ssv9MaR0a2i92G0TwHK8Q?e=KN3NIppm2kg&action=embedview&wdbipreview=true). -A video recording of this tutorial can be found [here]( -https://www.youtube.com/watch?v=T67wzFd1gVY). +Once pushed to the forked repository, the pull request will automatically update with your changes. +A reviewer will then review your changes and, if necessary, ask for further changes, or approve your pull-request. diff --git a/_pages/documentation/general_docs/common-errors.md b/_pages/documentation/general_docs/common-errors.md index 94e853eb5..4bdcf8cf5 100644 --- a/_pages/documentation/general_docs/common-errors.md +++ b/_pages/documentation/general_docs/common-errors.md @@ -148,6 +148,20 @@ From here, pre-commit will always run whenever you use `git commit`. However, if you've already committed these files, you can manually check that pre-commit still passes by running `pre-commit run --files ` to check specific files, `pre-commit run --all-files` for testing the entire directory, or `pre-commit run ` for individual hooks. When running these commands, pre-commit will both detect any style issues, and automatically reformat the files for you. +## Change-ID + +If you're running into issues getting you continuous integration tests to pass on GitHub, you may be forgetting to add a Change-Id to your commit message. +Though we have migrated away from using Gerrit, we still require the addition of a Change-Id. +In order to amend your commit and have all our checks pass, you must install the commit message hook from Gerrit. +You can install and update your commit by running the following commands below. + +```bash +n f=.git/hooks/commit-msg ; mkdir -p ; curl -Lo https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x +git commit --amend --no-edit +``` + +If you want more information on the commit message hook, read [here](https://gerrit-review.googlesource.com/Documentation/cmd-hook-commit-msg.html), and if you want to know more about Change-Ids, look [here](https://gerrit-review.googlesource.com/Documentation/user-changeid.html) + ## Further Issues If you continue to run into errors using gem5, feel free to ask questions in our [Slack channel](https://join.slack.com/t/gem5-workspace/shared_invite/zt-1c8go4yjo-LNb7l~BZ0FagwmVxX08y9g) or [mailing lists](https://www.gem5.org/mailing_lists). diff --git a/_pages/documentation/learning_gem5/part2/part2_3_events.md b/_pages/documentation/learning_gem5/part2/part2_3_events.md index 6059ce657..9817d3df6 100644 --- a/_pages/documentation/learning_gem5/part2/part2_3_events.md +++ b/_pages/documentation/learning_gem5/part2/part2_3_events.md @@ -42,7 +42,7 @@ class HelloObject : public SimObject EventFunctionWrapper event; public: - HelloObject(HelloObjectParams *p); + HelloObject(const HelloObjectParams &p); void startup(); }; @@ -61,7 +61,7 @@ any function you want. Below, we captute `this` in the lambda (`[this]`) so we can call member functions of the instance of the class. ```cpp -HelloObject::HelloObject(HelloObjectParams *params) : +HelloObject::HelloObject(const HelloObjectParams ¶ms) : SimObject(params), event([this]{processEvent();}, name()) { DPRINTF(HelloExample, "Created the hello object\n"); @@ -158,7 +158,7 @@ Then, in the constructor add default values for the `latency` and `timesLeft`. ```cpp -HelloObject::HelloObject(HelloObjectParams *params) : +HelloObject::HelloObject(const HelloObjectParams ¶ms) : SimObject(params), event([this]{processEvent();}, name()), latency(100), timesLeft(10) { diff --git a/_pages/documentation/reporting_problems.md b/_pages/documentation/reporting_problems.md index 83bf15c6b..e76da3ab3 100644 --- a/_pages/documentation/reporting_problems.md +++ b/_pages/documentation/reporting_problems.md @@ -30,8 +30,8 @@ reporting an issue: 2. Ensure you're compiling and running the latest version of [gem5]( https://github.com/gem5/gem5). The issue may have already been resolved. -3. Check changes [currently under review on our Gerrit system]( -https://gem5-review.googlesource.com/dashboard/self). It's possible a fix to +3. Check changes [currently under review on our GitHub system]( +https://github.com/gem5/gem5/pulls/). It's possible a fix to your issue is already on its way to being merged into the project. 4. Make sure you're running with `gem5.opt` or `gem5.debug`, not `gem5.fast`. diff --git a/_pages/events/isca-2023.md b/_pages/events/isca-2023.md index 2733e63c8..d70df7fcd 100644 --- a/_pages/events/isca-2023.md +++ b/_pages/events/isca-2023.md @@ -128,10 +128,10 @@ Those with posters may hang their poster at the start of the workshop (from 9:00 ### Accepted Posters -* **Analyzing Google Workload Traces in gem5** by Ayaz Akram, Maryam Babaie, and Jason Lowe-Power (University of California, Davis), [PDF](/assets/files/workshop-isca-2023/posters/analyzing-google-workload-traces-in-gem5.pdf) +* **Analyzing Google Workload Traces in gem5** by Ayaz Akram, Maryam Babaie, and Jason Lowe-Power (University of California, Davis), [PDF](/assets/files/workshop-isca-2023/posters/analyzing-google-workload-traces-in-gem5-poster.pdf) * **Octopi-cache: An AMD EPYC-like Three-Level Cache Model in gem5** by Hoa Nguyen and Jason Lowe-Power (University of California, Davis) * **Improving the Speed of gem5's GPU Regression Tests** by James Braun and Matthew D. Sinclair (University of Wisconsin, Madison) * **HammerSim: A tool to model RowHammer** by Kaustav Goswami, Ayaz Akram, Hari Venugopalan, and Jason Lowe-Power (University of California, Davis) -* **Validating Hardware and SimPoints with gem5: A RISC-V Board Case Study** by Kunal Pai and Jason Lowe-Power (University of California, Davis), [PDF](/assets/files/workshop-isca-2023/posters/validating-hardware-and-simpoints-with-gem5.pdf) +* **Validating Hardware and SimPoints with gem5: A RISC-V Board Case Study** by Kunal Pai, Zhantong Qiu, and Jason Lowe-Power (University of California, Davis), [PDF](/assets/files/workshop-isca-2023/posters/validating-hardware-and-simpoints-with-gem5-poster.pdf) * **QPoints: QEMU to gem5 ARM** by Bhargav Reddy Godala, Ishita Chaturvedi, Yucan Wu (Princeton University), [PDF](/assets/files/workshop-isca-2023/posters/qpoints.pdf) -* **gem5 Vision** by Parth Shah, Kunal Pai, Harshil Patel, and Arslan Ali (University of California, Davis), [PDF](/assets/files/workshop-isca-2023/posters/gem5-vision.pdf) +* **gem5 Vision** by Parth Shah, Kunal Pai, Harshil Patel, and Arslan Ali (University of California, Davis), [PDF](/assets/files/workshop-isca-2023/posters/gem5-vision-poster.pdf) diff --git a/_pages/join-slack.md b/_pages/join-slack.md new file mode 100644 index 000000000..d35089561 --- /dev/null +++ b/_pages/join-slack.md @@ -0,0 +1,14 @@ +--- +layout: page +title: Join Slack +permalink: /join-slack/ +--- + + + + + + +

You will be redirected to the gem5 Slack invite soon!

+ + diff --git a/index.html b/index.html index ca57364be..2b4f75e14 100755 --- a/index.html +++ b/index.html @@ -19,9 +19,9 @@ - + - +