Skip to content

Latest commit

 

History

History
100 lines (66 loc) · 4.72 KB

CONTRIBUTING.md

File metadata and controls

100 lines (66 loc) · 4.72 KB
Raw

GUIDE TO CONTRIBUTING

  1. If you need help on making a pull request, follow this guide.

  2. To understand how to compile and test chisel3 from the source code, follow the instructions in SETUP.md.

  3. In order to contribute to chisel3, you'll need to sign the CLA agreement. You will be asked to sign it upon your first pull request.

  1. To introduce yourself and get help, you can join the gitter forum. If you have any questions or concerns, you can get help there.

  2. You can peruse the good-first-issues for easy tasks to start with. Another easy thing to start with is doing your own pass of the website looking for typos, pages missing their titles, etc. The sources for the website are here.

  3. Please make your PRs against the master branch. The project admins, when reviewing your PR, will decide which stable version (if any) your change should be backported to. The backports will be opened automatically on your behalf once your master PR is merged.

  4. The PR template will require you to select "Type of Improvement." A reviewer or someone with write access will add the appropriate label to your PR based on this type of improvement which will include your PR in the correct category in the release notes.

  5. If your backport PR(s) get labeled with bp-conflict, it means they cannot be automatically be merged. You can help get them merged by openening a PR against the already-existing backport branch (will be named something like mergify/bp/3.5.x/pr-2512) with the necessary cleanup changes. The admins will merge your cleanup PR and remove the bp-conflict label if appropriate.

Frequently Asked Questions

I'm failing the scalafmt check. How do I make sure my code is formatted?

From the Chisel3 root directory, run:

sbt scalafmtAll

You may need to specify the version, at time of writing this is:

sbt ++2.12.15 scalafmtAll

How do I update PRs from before Scalafmt was applied?

Just before the release of Chisel v3.5.0, we started using Scalafmt in this repository. Scalafmt is a code formatter; thus when it was applied in chipsalliance#2246 it caused a nearly 10,000 line diff. This introduces merge conflicts with almost every single branch from before that change. In some cases, it can be simple enough to just resolve any conflicts with a standard merge or rebase, but for some branches, this is too complicated. For such complex cases, we recommend the following procedure.

Merge-based flow

To make the following commands copy-pastable, we recommend exporting your branch name as an environment variable:

export MY_BRANCH=<name of your branch>

First, you should back up a copy of your branch in case anything goes wrong.

git branch $MY_BRANCH-backup

We also need to make sure that you have the upstream Chisel repo as a remote.

git remote add upstream https://github.com/chipsalliance/chisel3.git
git fetch upstream

You can then run the following commands:

# Make sure your branch is checked out
git checkout $MY_BRANCH

# Merge with the commit just before Scalafmt was applied
# It is possible you will have to resolve conflicts at this point
git merge upstream/just-before-scalafmt
# just-before-scalafmt is a branch that points to a commit, in case the branch gets deleted, you can instead run:
# git branch just-before-scalafmt dd36f97a82746cec0b25b94651581fe799e24579
# git merge just-before-scalafmt

# Format everything using Scalafmt
sbt scalafmtAll

# Commit the reformatted code
git commit -a -m 'Apply Scalafmt'

# Now we need to merge our changes with just after Scalafmt as applied
# Any conflicts are from our changes so we tell git to resolve conflicts by picking our changes
git merge upstream/just-after-scalafmt -X ours
# just-before-scalafmt is a branch that points to a commit, in case the branch gets deleted, you can instead run:
# git branch just-after-scalafmt 3131c0daad41dea78bede4517669e376c41a325a
# git merge just-after-scalafmt -X ours

# Most conflicts from code formatting should be resolved, now you can merge master
# There may still be some silly conflicts, but most should be avoided
git merge upstream/master

# Don't forget to push your changes!
git push origin $MY_BRANCH