2021-05-02 11:13:38 +02:00
|
|
|
# Contributing to Dogecoin Core
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2021-05-25 17:40:02 +02:00
|
|
|
Dogecoin Core is an open source project, and we would welcome contributions which provably
|
|
|
|
improve the state of the software. For those wanting to discuss changes, or look for work
|
|
|
|
that needs doing, please see:
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2021-06-03 19:13:15 +02:00
|
|
|
* [Help requests](https://github.com/dogecoin/dogecoin/labels/help%20wanted)
|
2021-05-25 17:40:02 +02:00
|
|
|
* [Projects](https://github.com/dogecoin/dogecoin/projects)
|
|
|
|
* [Dogecoindev on reddit](https://www.reddit.com/r/dogecoindev/)
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2021-05-25 17:40:02 +02:00
|
|
|
## Branch Strategy
|
|
|
|
|
2021-06-03 19:28:48 +02:00
|
|
|
Dogecoin Core's default branch is intentionally a stable release, so that anyone
|
|
|
|
downloading the code and compiling it gets a stable release. Active development
|
|
|
|
occurs on branches named after the version they are targeting, for example the
|
|
|
|
1.14.4 branch is named `1.14.4-dev`. When raising PRs, please raise against the
|
|
|
|
relevant development branch and **not** against the `master` branch.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2021-05-02 11:13:38 +02:00
|
|
|
## Contributor Workflow
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
The codebase is maintained using the "contributor workflow" where everyone
|
|
|
|
without exception contributes patch proposals using "pull requests". This
|
|
|
|
facilitates social contribution, easy testing and peer review.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
|
|
|
To contribute a patch, the workflow is as follows:
|
|
|
|
|
2021-06-03 19:17:52 +02:00
|
|
|
- Fork the repository in GitHub, and clone it your development machine.
|
|
|
|
- Create a topic branch from the relevant development branch.
|
|
|
|
- Commit changes to the branch.
|
|
|
|
- Test your changes, which **must** include the unit and RPC tests passing.
|
2021-05-25 17:40:02 +02:00
|
|
|
- Push topic branch to your copy of the repository.
|
2021-06-03 19:17:52 +02:00
|
|
|
- Raise a Pull Request via GitHub.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
The project coding conventions in the [developer notes](doc/developer-notes.md)
|
|
|
|
must be adhered to.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
In general [commits should be atomic](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_commit_convention)
|
|
|
|
and diffs should be easy to read. For this reason do not mix any formatting
|
|
|
|
fixes or code moves with actual code changes.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
Commit messages should be verbose by default consisting of a short subject line
|
|
|
|
(50 chars max), a blank line and detailed explanatory text as separate
|
|
|
|
paragraph(s); unless the title alone is self-explanatory (like "Corrected typo
|
2017-02-15 08:00:04 +01:00
|
|
|
in init.cpp") then a single title line is sufficient. Commit messages should be
|
2016-06-20 01:15:36 +02:00
|
|
|
helpful to people reading your code in the future, so explain the reasoning for
|
|
|
|
your decisions. Further explanation [here](http://chris.beams.io/posts/git-commit/).
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
If a particular commit references another issue, please add the reference, for
|
|
|
|
example `refs #1234`, or `fixes #4321`. Using the `fixes` or `closes` keywords
|
|
|
|
will cause the corresponding issue to be closed when the pull request is merged.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
Please refer to the [Git manual](https://git-scm.com/doc) for more information
|
|
|
|
about Git.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
|
|
|
- Push changes to your fork
|
|
|
|
- Create pull request
|
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
The body of the pull request should contain enough description about what the
|
|
|
|
patch does together with any justification/reasoning. You should include
|
|
|
|
references to any discussions (for example other tickets or mailing list
|
|
|
|
discussions).
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
At this stage one should expect comments and review from other contributors. You
|
|
|
|
can add more commits to your pull request by committing them locally and pushing
|
|
|
|
to your fork until you have satisfied all feedback.
|
2016-05-10 08:23:49 +02:00
|
|
|
|
2021-05-02 11:13:38 +02:00
|
|
|
|
|
|
|
## Squashing Commits
|
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
If your pull request is accepted for merging, you may be asked by a maintainer
|
|
|
|
to squash and or [rebase](https://git-scm.com/docs/git-rebase) your commits
|
|
|
|
before it will be merged. The basic squashing workflow is shown below.
|
2016-05-10 08:23:49 +02:00
|
|
|
|
|
|
|
git checkout your_branch_name
|
|
|
|
git rebase -i HEAD~n
|
|
|
|
# n is normally the number of commits in the pull
|
|
|
|
# set commits from 'pick' to 'squash', save and quit
|
|
|
|
# on the next screen, edit/refine commit messages
|
|
|
|
# save and quit
|
|
|
|
git push -f # (force push to GitHub)
|
|
|
|
|
2016-09-21 11:44:05 +02:00
|
|
|
If you have problems with squashing (or other workflows with `git`), you can
|
|
|
|
alternatively enable "Allow edits from maintainers" in the right GitHub
|
|
|
|
sidebar and ask for help in the pull request.
|
|
|
|
|
|
|
|
Please refrain from creating several pull requests for the same change.
|
|
|
|
Use the pull request that is already open (or was created earlier) to amend
|
|
|
|
changes. This preserves the discussion and review that happened earlier for
|
|
|
|
the respective change set.
|
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
The length of time required for peer review is unpredictable and will vary from
|
|
|
|
pull request to pull request.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
|
|
|
|
2021-05-02 11:13:38 +02:00
|
|
|
## Pull Request Philosophy
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2021-06-03 19:24:58 +02:00
|
|
|
Pull Requests should always be focused. For example, a pull request could add a
|
|
|
|
feature, fix a bug, or refactor code; but not a mixture. Please avoid submitting
|
|
|
|
pull requests that attempt to do too much, are overly large, or overly complex
|
2016-06-20 01:15:36 +02:00
|
|
|
as this makes review difficult.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
|
|
|
|
2021-05-02 11:13:38 +02:00
|
|
|
### Features
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
When adding a new feature, thought must be given to the long term technical debt
|
|
|
|
and maintenance that feature may require after inclusion. Before proposing a new
|
|
|
|
feature that will require maintenance, please consider if you are willing to
|
|
|
|
maintain it (including bug fixing). If features get orphaned with no maintainer
|
|
|
|
in the future, they may be removed by the Repository Maintainer.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
|
|
|
|
2021-05-02 11:13:38 +02:00
|
|
|
### Refactoring
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
Refactoring is a necessary part of any software project's evolution. The
|
|
|
|
following guidelines cover refactoring pull requests for the project.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
There are three categories of refactoring, code only moves, code style fixes,
|
|
|
|
code refactoring. In general refactoring pull requests should not mix these
|
|
|
|
three kinds of activity in order to make refactoring pull requests easy to
|
|
|
|
review and uncontroversial. In all cases, refactoring PRs must not change the
|
|
|
|
behaviour of code within the pull request (bugs must be preserved as is).
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
Project maintainers aim for a quick turnaround on refactoring pull requests, so
|
|
|
|
where possible keep them short, uncomplex and easy to verify.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
|
|
|
|
2021-05-02 11:13:38 +02:00
|
|
|
## "Decision Making" Process
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2021-06-03 19:24:58 +02:00
|
|
|
The following applies to code changes to Dogecoin Core, and is not to be
|
|
|
|
confused with overall Dogecoin Network Protocol consensus changes. All consensus
|
|
|
|
changes **must** be ratified by miners; a proposal to implement protocol changes
|
|
|
|
does not guarantee activation on the mainnet, not even when a binary gets
|
|
|
|
released by maintainers.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2021-06-03 19:24:58 +02:00
|
|
|
Whether a pull request is merged into Dogecoin Core rests with the repository
|
2021-05-25 17:40:02 +02:00
|
|
|
maintainers.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
Maintainers will take into consideration if a patch is in line with the general
|
2021-06-03 19:24:58 +02:00
|
|
|
principles of Dogecoin; meets the minimum standards for inclusion; and will
|
|
|
|
take into account the consensus among frequent contributors.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
|
|
|
In general, all pull requests must:
|
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
- have a clear use case, fix a demonstrable bug or serve the greater good of
|
2021-06-03 19:24:58 +02:00
|
|
|
Dogecoin;
|
|
|
|
- be peer reviewed;
|
|
|
|
- have unit tests and functional tests;
|
2015-09-24 15:28:07 +02:00
|
|
|
- follow code style guidelines;
|
|
|
|
- not break the existing test suite;
|
2016-06-20 01:15:36 +02:00
|
|
|
- where bugs are fixed, where possible, there should be unit tests
|
2021-06-03 19:24:58 +02:00
|
|
|
demonstrating the bug and also proving the fix. This helps prevent
|
|
|
|
regressions.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2021-06-03 19:24:58 +02:00
|
|
|
The following patch types are expected to have significant discussion before
|
|
|
|
approval and merge:
|
|
|
|
|
|
|
|
- Consensus rule changes (through softfork or otherwise)
|
|
|
|
- Policy changes
|
|
|
|
|
|
|
|
While each case will be different, one should be prepared to expend more time
|
|
|
|
and effort than for other kinds of patches because of increased peer review
|
|
|
|
and consensus building requirements.
|
2015-09-24 15:28:07 +02:00
|
|
|
|
|
|
|
|
2021-05-02 11:13:38 +02:00
|
|
|
### Peer Review
|
2015-09-24 15:28:07 +02:00
|
|
|
|
2016-06-20 01:15:36 +02:00
|
|
|
Anyone may participate in peer review which is expressed by comments in the pull
|
|
|
|
request. Typically reviewers will review the code for obvious errors, as well as
|
2021-06-03 19:24:58 +02:00
|
|
|
test out the patch set and opine on the technical merits of the patch.
|
|
|
|
Repository maintainers take into account the peer review when determining if
|
|
|
|
there is consensus to merge a pull request.
|
|
|
|
|
|
|
|
Maintainers reserve the right to weigh the opinions of peer reviewers
|
2016-06-20 01:15:36 +02:00
|
|
|
using common sense judgement and also may weight based on meritocracy: Those
|
2021-06-03 19:24:58 +02:00
|
|
|
that have demonstrated a deeper commitment and understanding towards Dogecoin
|
2016-06-20 01:15:36 +02:00
|
|
|
(over time) or have clear domain expertise may naturally have more weight, as
|
|
|
|
one would expect in all walks of life.
|
|
|
|
|
2021-05-14 18:37:05 +02:00
|
|
|
Where a patch set proposes to change the Dogecoin consensus, it must have been
|
2021-06-03 19:24:58 +02:00
|
|
|
discussed extensively, be accompanied by widely discussed documentation and have
|
|
|
|
a generally widely perceived technical consensus of being a worthwhile change,
|
|
|
|
based on the judgement of the maintainers.
|
2016-09-22 03:58:18 +02:00
|
|
|
|
2021-05-02 11:13:38 +02:00
|
|
|
## Copyright
|
2016-09-22 03:58:18 +02:00
|
|
|
|
|
|
|
By contributing to this repository, you agree to license your work under the
|
|
|
|
MIT license unless specified otherwise in `contrib/debian/copyright` or at
|
|
|
|
the top of the file itself. Any work contributed where you are not the original
|
|
|
|
author must contain its license header with the original author(s) and source.
|