- PR/Issues Naming Standard Format
- When to Search the Issue Tracker
- When to Submit a New Issue
- When to Submit a Pull Request
- How to Contribute
- Go Development Tips
- Working with gRPC
For efficient records keeping and retrieval, the following should be used as the PR/Issues naming standard whenever possible:
[Package/File/Directory Name]: [Concise and concrete description of the PR/Issue]
Package/File/Directory Name
- Represents the collective name of the container in which the changes requested, belong to.
examples of valid PR/Issues naming formats:
- net/url: Parsing 192.168.12.12:8080 returns an error (Issue)
- views/home: data-type of size column needs to be "size" (PR)
- db/dcrpg: Charts data updates could use incremental changes. (Issue)
- doc/contributing.md: Updating the users contribution guidelines. (PR)
If any of the following apply:
- You believe you found a bug. It might already be logged, or even have a fix underway!
- You have an idea for an enhancement or new feature. Before you start coding away and submit a PR for your work, consult the issue tracker.
- You just want to find something to work on.
New issues may be submitted for enhancement requests as well as bug reports. However, we ask that you please search first for similar existing issues to avoid posting a duplicate.
You are strongly advised to submit a new issue when you plan to perform work and submit a pull request (PR). See When to Submit a Pull Request below.
A related matter of GitHub etiquette is when and how to post comments on Issues or PRs. Instead of simply posting "mee to! plus one", you can use the emoji responses to give a +1 or thumbs up. Feel free to comment if you have more to add to the conversation.
Before submitting a PR, check the issue tracker for existing issues or relevant discussion. See what has been done, if anything. Perhaps there is good reason why certain changes have not already been made.
If the planned commits will involve significant effort on your part, you definitely want to either (1) submit a new issue, or (2) announce your intention to work on an existing issue. Why? Someone else could already be working on the problem. Duplicating work really sucks. Also, there may be good reason why the change is not appropriate at the time. The best way to check is to head to the issue tracker.
Only submit a PR once the intended edits are either done or nearing completion. When submitting a PR with incomplete work, "Work in progress" or "WIP" should be prefixed to the PR title or prominently displayed in the description.
- Go - the latest release or the one immediately prior (e.g. 1.21 or 1.20).
- git client with command line support. download
- GitHub account
- Visual Studio Code with Go extension plus
gometalinter
- Coffee, preferably black.
- Fork the repository on GitHub. Just click the little Fork button at https://github.com/decred/dcrdata
- Clone your newly forked dcrdata repository
git clone git@github.com:my-user-name/dcrdata.git
Setting your master branch to track this repository makes keeping everything up-to-date a breeze. The rest of this workflow guide will assume that you have completed this step.
git remote add upstream https://github.com/decred/dcrdata.git
git fetch upstream
git branch -u upstream/master master
- Make a branch for your planned work, based on
master
git checkout -b my-great-stuff master
- Make edits. Review changes:
git status
git diff
- Commit your work
# pick files you modified
git add -u
# don't forget to add that new file you made too
git add newfile.go
# one more check
git status
# make the commit
git commit # type a good commit message
- Bring master up-to-date and rebase
Since the Decred repo may have changes that you do not have locally, you'll want to pull in any changes and rebase. Read this if you need a primer on rebasing.
git checkout master
git pull
git checkout my-great-stuff
git rebase -i master
In the text editor, change the command from pick
to fixup
or squash
for all but the top commit. Use fixup
for little touchups to discard the commit's log message. If you want to use a different
commit message for everything, change the command from pick
to reword
on the top commit.
It should look something like this before saving.
- If you have conflicts, resolve them by iterating through the diffs one conflicting commit at a time.
# resolve conflicts
git add file1.go, file2.go, ...
git rebase --continue
# repeat until rebase completes
- Push your branch to GitHub
Assuming myremote
is the name of the remote used for your repository (by default, git created an alias, origin
, for your forked repository in step 2 above, but you can name it whatever you'd like):
git push -u myremote my-great-stuff
- Create the pull request
On Github, select your branch in the dropdown menu (1) and click (2) to start a pull request.
Always:
- Type a detailed comment for the changes you are proposing. Include motivation and a description of the code change.
- Highlight any breaking changes. This includes any syntax changes, added or removed struct fields, interface changes, file renames or deletions, etc.
- Scroll down and review the code diffs. Verify that the changes are what you expect to see based on your earlier review of the diffs and your git commit log (you did that, right?).
Excellent PR guidelines from Kubernetes project.
- Receive feedback and make changes
You will typically receive feedback from other developers. Before responding, take a moment to review the Code Contribution Guidelines.
Work through the comments and resolve any confusion with others. Make whatever revisions are necessary.
- Resubmitting
Commit your work as in step 5 above.
Before resubmitting, clean up any little touchup commits you've made since the last time you pushed. If you've only made one commit since then, you can skip this step. For example, if you have made 3 commits since your last push, then run the following to "squash" them together.
git rebase -i HEAD~3
The number after the tilde (~) is the number of commits that you want to combine, including the one you did at the beginning of this step. Try not to squash post-review commits with pre-review commits. Leaving them separate makes navigating the changes easier.
Then rebase the entire branch back to an updated master.
git checkout master
git pull
git checkout my-great-stuff
git rebase master
Note that the 4th command is different than step 6. You already performed the squash in the last step, so an interactive rebase (-i
) is not needed here.
Push the changes to your remote fork.
git push myremote my-great-stuff
Depending on what has changed, you will likely receive an error message rejecting your push for a misaligned branch tip. This is normal.
Rerun with the --force
flag.
As soon as you push, your changes will be ready for review. There is typically no need to notify anybody that the changes have been made. Github takes care of that. Feel free to leave a comment on the pull request with a brief description of your changes.
Use code linters. gometalinter
is suggested to run the whole lot.
Always go fmt
your code before committing.
Read Effective Go.
If you work with any gRPC components, you'll need up-to-date
protoc
and the protoc-gen-go
packages.
If you update a gRPC protocol buffer file (.proto file extension), make sure to recompile the go type definitions.
You can use the script at
dcdrrates/runprotoc.sh
to recompile dcrrates.pb.go
.
Code Contribution Guidelines (dcrd repo)