Skip to content

Latest commit

 

History

History
234 lines (153 loc) · 9.28 KB

CONTRIBUTING.md

File metadata and controls

234 lines (153 loc) · 9.28 KB
Raw

Contributing

Contents

Guidelines

PR/Issues Naming Standard Format

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)

When to Search the Issue Tracker

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.

When to Submit a New Issue

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.

When to Submit a Pull Request

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.

How to Contribute

Suggested Toolkit

  • 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.

Git Workflow

  1. Fork the repository on GitHub. Just click the little Fork button at https://github.com/decred/dcrdata

image

  1. Clone your newly forked dcrdata repository
git clone [email protected]:my-user-name/dcrdata.git
recommended

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
  1. Make a branch for your planned work, based on master
git checkout -b my-great-stuff master
  1. Make edits. Review changes:
git status
git diff
  1. 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
  1. 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.

alt text

  1. 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
  1. 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
  1. Create the pull request

On Github, select your branch in the dropdown menu (1) and click (2) to start a pull request.

alt text

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.

  1. 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.

  1. Resubmitting

Commit your work as in step 5 above.

a)

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.

b)

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.

c)

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.

Go Development Tips

Use code linters. gometalinter is suggested to run the whole lot.

Always go fmt your code before committing.

Read Effective Go.

Working with gRPC

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.

Further reading

Code Contribution Guidelines (dcrd repo)