Forking#

You will need your own fork to work on the code. Go to theOpenROAD projectpage and hit theFork button. You willwant to clone your fork to your machine:

gitclonehttps://github.com/your-user-name/OpenROAD.gitcdOpenROADgitremoteaddupstreamhttps://github.com/The-OpenROAD-Project/OpenROAD.gitgitfetchupstream

This creates the directoryOpenROAD and connects your repository tothe upstream (master project)OpenROAD repository.

Creating a branch#

You want your master branch to reflect only production-ready code, so create afeature branch for making your changes. For example:

gitcheckoutmaster&&gitbranchshiny-new-featuregitcheckoutshiny-new-feature# Or equivalently,gitcheckoutmaster&&checkout-bshiny-new-feature

This changes your working directory to the shiny-new-feature branch. Keep anychanges in this branch specific to one bug or feature so it is clearwhat the branch brings to OpenROAD. You can have many shiny-new-featuresand switch in between them using the git checkout command.

When creating this branch, make sure your master branch is up to date withthe latest upstream master version. To update your local master branch, youcan do:

gitcheckoutmastergitpullupstreammaster

When you want to update the feature branch with changes in master afteryou created the branch, check the section onupdating a PR.

Committing your code#

Keep style fixes to a separate commit to make your pull request more readable. Once you’ve made changes, you can see them by typing:

gitstatus

If you have created a new file, it is not being tracked by git. Add it by typing:

gitaddpath/to/file-to-be-added.py

Doinggitstatus again should give something like:

# On branch shiny-new-feature##       modified:   /relative/path/to/file-you-added.py#

Finally, commit your changes to your local repository with an explanatory commitmessage. Do note the-s option is needed for developer signoff.

gitcommit-s-m"your commit message goes here"

Pushing your changes#

When you want your changes to appear publicly on your GitHub page, push yourforked feature branch’s commits:

gitpushoriginshiny-new-feature

Hereorigin is the default name given to your remote repository on GitHub.You can see the remote repositories:

gitremote-v

If you added the upstream repository as described above you will see somethinglike:

originhttps://github.com/your-user-name/OpenROAD.git(fetch)originhttps://github.com/your-user-name/OpenROAD.git(push)upstreamhttps://github.com/The-OpenROAD-Project/OpenROAD.git(fetch)upstreamhttps://github.com/The-OpenROAD-Project/OpenROAD.git(push)

Now your code is on GitHub, but it is not yet a part of the OpenROAD project. For that tohappen, a pull request needs to be submitted on GitHub.

Review your code#

When you’re ready to ask for a code review, file a pull request. Before you do, onceagain make sure that you have followed all the guidelines outlined in theDeveloper’s Guideregarding code style, tests, performance tests, and documentation. You should alsodouble check your branch changes against the branch it was based on:

1. Navigate to your repository on GitHub – https://github.com/your-user-name/OpenROAD

2. Click onBranches

3. Click on theCompare button for your feature branch

4. Select thebase andcompare branches, if necessary. This will bemaster andshiny-new-feature, respectively.

Submitting the pull request#

If everything looks good, you are ready to make a pull request. A pull request is howcode from a local repository becomes available to the GitHub community and can be lookedat and eventually merged into the master version. This pull request and its associatedchanges will eventually be committed to the master branch and available in the nextrelease. To submit a pull request:

1. Navigate to your repository on GitHub

2. Click on theCompare&pullrequest button

3. You can then click onCommits andFilesChanged to make sure everything looksokay one last time

4. Write a description of your changes in thePreviewDiscussion tab

5. ClickSendPullRequest.

This request then goes to the repository maintainers, and they will reviewthe code.

Updating your pull request#

Based on the review you get on your pull request, you will probably need to makesome changes to the code. In that case, you can make them in your branch,add a new commit to that branch, push it to GitHub, and the pull request will beautomatically updated. Pushing them to GitHub again is done by:

gitpushoriginshiny-new-feature

This will automatically update your pull request with the latest code and restart theContinuous Integration tests.

Another reason you might need to update your pull request is to solve conflictswith changes that have been merged into the master branch since you opened yourpull request.

To do this, you need tomergeupstreammaster in your branch:

gitcheckoutshiny-new-featuregitfetchupstreamgitmergeupstream/master

If there are no conflicts (or they could be fixed automatically), a file with adefault commit message will open, and you can simply save and quit this file.

If there are merge conflicts, you need to solve those conflicts. Seethisarticlefor an explanation on how to do this.Once the conflicts are merged and the files where the conflicts were solved areadded, you can rungitcommit to save those fixes.

If you have uncommitted changes at the moment you want to update the branch withmaster, you will need tostash them prior to updating.

This will effectively store your changes and they can be reapplied after updating.

After the feature branch has been updated locally, you can now update your pullrequest by pushing to the branch on GitHub:

gitpushoriginshiny-new-feature

Tips for a successful pull request#

If you have made it to theReviewyourcode phase, one of the core contributors maytake a look. Please note however that a handful of people are responsible for reviewingall of the contributions, which can often lead to bottlenecks.

To improve the chances of your pull request being reviewed, you should:

• Reference an open issue for non-trivial changes to clarify the PR’s purpose

• Ensure you have appropriate tests. These should be the first part of any PR

• Keep your pull requests as simple as possible. Larger PRs take longer to review

• Ensure that CI is in a green state. Reviewers may not even look otherwise

• Keep updating your pull request, either by request or every few days

Acknowledgements#

This page has been adapted frompandas Developer Guide.