Home - StanfordAHA/CGRAFlow GitHub Wiki

Projects

Directly Responsible Individual (You!)

If you merge changes into the master branch of one of the above repos, you are directly responsible for ensuring that the CGRAFlow Travis badge stays green. If your changes introduce a bug, fix it. If you changed your API, delegate the task to the appropriate project/team/individual.

IMPORTANT: Even though you may have delegated tasks to someone else, you are still responsible for keeping the flow green. That means you should not merge any of your changes until any issues have been resolved. That also means that you are the one responsible for ensuring that your delegated tasks are completed.

Workflow

How to sleep easy at night knowing that you didn't break the master branch

Step 1: Implement changes local to your project

  1. In your local project, create a branch <your_local_branch> for every new feature, bug fix, or refactor. Examples:
% git rev-parse --show-toplevel
  /nobackup/steveri/github/CGRAGenerator

% git checkout -b feature/line-buffers
% git checkout -b bugfix/off-by-one-error
% git checkout -b refactor/python-api

  1. Write a test (preferably more than one)

  2. Make the test(s) pass and push your changes to Github.

Step 2: Make sure your changes work globally in CGRAFlow

  1. Create a branch on the CGRAFlow repository.
% git rev-parse --show-toplevel
  /nobackup/steveri/github/CGRAFlow
% git checkout -b <your_cgraflow_branch>
  1. Edit the Travis script in <your_cgraflow_branch> to use your repository's new branch <your_local_branch>.
-  - git clone https://github.com/cdonovick/smt-pnr
+  - git clone -b refactor/python-api https://github.com/cdonovick/smt-pnr
  1. Push <your_cgraflow_branch> to Github to trigger a Travis build.
git push -u origin <your_cgraflow_branch>
  1. Ensure that the Travis build passes: CGRAFlow Travis branch page. If it fails due to another project (i.e. you changed your API), notify them (github issues, slack, in person).
    NOTE: They will need to follow these same steps, except they should use <your_cgraflow_branch> on the CGRAFlow repository (editing the script to checkout their new branch).
    TODO: Clarify, this (step 2.4) is confusing. If you are confused reading this, ask someone for clarification on the procedure.
TODOs

Implement a script for steps 2a-c

Step 3: File a pull request to finalize your changes

  1. Open a pull request see link to merge <your_local_branch> back into your local repository's master. Request at least one reviewer that is not you. Include a link to the passing Travis build for the CGRAFlow (example).

  2. Once the review is completed and the pull request approved, you (or one of the reviewers) can merge the pull request back into the master branch of your local repository see link and then delete <your_local_branch> as well as the no-longer-needed CGRAFlow branch <your_cgraflow_branch>.

Pull Request Best Practices

Copied from the FIRRTL Wiki

  • Small PR => Easy to understand PR => Fast to review PR => Happy Reviewer :)
  • Bugfix should be accompanied with a corresponding test case demonstrating the bug (and it must pass).
  • Feature addition should be accompanied with a suite of tests
  • Separate functional changes from style changes (make them two separate PR's)

Enforcing Best Practices

Further Reading

Thoughtbot guides