Skip to content

doc: Updated notes on how to contribute to Bitcoin Knots. #314

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pdath wants to merge 2 commits into
base: 29.x-knots
Choose a base branch
from
Open

doc: Updated notes on how to contribute to Bitcoin Knots. #314

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6dd81c5
doc: Updated notes on how to contribute to Bitcoin Knots.
pdath Jun 16, 2026
ab0fb5e
Changed Bitcoin Knots Communication Channels.
pdath Jul 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 22 additions & 48 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ welcome to contribute towards development in the form of peer review, testing
and patches. This document explains the practical process and guidelines for
contributing.

First, in terms of structure, there is no particular concept of "core
First, in terms of structure, there is no particular concept of "knots
developers" in the sense of privileged people. Open source often naturally
revolves around a meritocracy where contributors earn trust from the developer
community over time. Nevertheless, some hierarchy is necessary for practical
Expand All @@ -24,19 +24,18 @@ as a new contributor. It also will teach you much more about the code and
process than opening pull requests. Please refer to the [peer review](#peer-review)
section below.

Before you start contributing, familiarize yourself with the Bitcoin Core build
Before you start contributing, familiarize yourself with the Bitcoin Knots build
system and tests. Refer to the documentation in the repository on how to build
Bitcoin Core and how to run the unit tests, functional tests, and fuzz tests.
Bitcoin Knots and how to run the unit tests, functional tests, and fuzz tests.

There are many open issues of varying difficulty waiting to be fixed.
If you're looking for somewhere to start contributing, check out the
[good first issue](https://github.com/bitcoin/bitcoin/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
list or changes that are
[up for grabs](https://github.com/bitcoin/bitcoin/issues?utf8=%E2%9C%93&q=label%3A%22Up+for+grabs%22).
[good first issue](https://github.com/bitcoinknots/bitcoin/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
list.
Some of them might no longer be applicable. So if you are interested, but
unsure, you might want to leave a comment on the issue first.

You may also participate in the [Bitcoin Core PR Review Club](https://bitcoincore.reviews/).
You may also participate in the [Bitcoin Knots Discord](https://discord.gg/3Ccegp9YrU).

### Good First Issue Label

Expand All @@ -51,25 +50,19 @@ you are encouraged to leave a comment if you are planning to work on it. This
will help other contributors monitor which issues are actively being addressed
and is also an effective way to request assistance if and when you need it.

Communication Channels
----------------------
Bitcoin Knots Communication Channels
------------------------------------
Comment thread
pdath marked this conversation as resolved.
Outdated

Most communication about Bitcoin development happens on IRC, in the
`#bitcoin-core-dev` channel on Libera Chat. The easiest way to participate on IRC is
with the web client, [web.libera.chat](https://web.libera.chat/#bitcoin-core-dev). Chat
history logs can be found
on [https://www.erisian.com.au/bitcoin-core-dev/](https://www.erisian.com.au/bitcoin-core-dev/)
and [https://gnusha.org/bitcoin-core-dev/](https://gnusha.org/bitcoin-core-dev/).
Most communication about Bitcoin Knots development happens on Discord, in the
`#dev` channel. You can join the Bitcoin Knots Discord with this [invitation
link](https://discord.gg/3Ccegp9YrU).

The easiest way to participate on Discord is with the web client,
[https://discord.com/channels/@me](https://discord.com/channels/@me).

Discussion about codebase improvements happens in GitHub issues and pull
requests.

The developer
[mailing list](https://groups.google.com/g/bitcoindev)
should be used to discuss complicated or controversial consensus or P2P protocol changes before working on
a patch set.
Archives can be found on [https://gnusha.org/pi/bitcoindev/](https://gnusha.org/pi/bitcoindev/).


Contributor Workflow
--------------------
Expand All @@ -84,25 +77,7 @@ To contribute a patch, the workflow is as follows:
1. Create topic branch
1. Commit patches

For GUI-related issues or pull requests, the https://github.com/bitcoin-core/gui repository should be used.
For all other issues and pull requests, the https://github.com/bitcoin/bitcoin node repository should be used.

The master branch for all monotree repositories is identical.

As a rule of thumb, everything that only modifies `src/qt` is a GUI-only pull
request. However:

* For global refactoring or other transversal changes the node repository
should be used.
* For GUI-related build system changes, the node repository should be used
because the change needs review by the build systems reviewers.
* Changes in `src/interfaces` need to go to the node repository because they
might affect other components like the wallet.

For large GUI changes that include build system and interface changes, it is
recommended to first open a pull request against the GUI repository. When there
is agreement to proceed with the changes, a pull request with the build system
and interfaces changes can be submitted to the node repository.
For all issues and pull requests, the https://github.com/bitcoinknots/bitcoin repository should be used.

The project coding conventions in the [developer notes](doc/developer-notes.md)
must be followed.
Expand Down Expand Up @@ -170,13 +145,13 @@ mailing list discussions).
The description for a new pull request should not contain any `@` mentions. The
PR description will be included in the commit message when the PR is merged and
any users mentioned in the description will be annoyingly notified each time a
fork of Bitcoin Core copies the merge. Instead, make any username mentions in a
fork of Bitcoin Knots copies the merge. Instead, make any username mentions in a
subsequent comment to the PR.

### Translation changes

Note that translations should not be submitted as pull requests. Please see
[Translation Process](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md)
[Translation Process](doc/translation_process.md)

@luke-jr luke-jr Jul 8, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doc itself needs revision since Core stole the repo

@pdath pdath Jul 9, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer to put that into a separate pull request. Otherwise, we may end up deferring this update while all documentation gets refreshed.
This is a primary document that new contributors will read, and getting into the LTS support train will help bring more developers on board faster.

for more information on helping with translations.

### Work in Progress Changes and Requests for Comments
Expand Down Expand Up @@ -232,7 +207,7 @@ pull request to pull request.

When a pull request conflicts with the target branch, you may be asked to rebase it on top of the current target branch.

@luke-jr luke-jr Jul 8, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't actually want rebasing here

@pdath pdath Jul 9, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shall I remove this sentence? Otherwise, what would be the correct approach?
I am very new to this project, so I am not familiar with these finer points.


git fetch https://github.com/bitcoin/bitcoin # Fetch the latest upstream commit
git fetch https://github.com/bitcoinknots/bitcoin # Fetch the latest upstream commit
git rebase FETCH_HEAD # Rebuild commits on top of the new base

This project aims to have a clean git history, where code changes are only made in non-merge commits. This simplifies
Expand Down Expand Up @@ -327,7 +302,7 @@ request. Typically reviewers will review the code for obvious errors, as well as
test out the patch set and opine on the technical merits of the patch. Project
maintainers take into account the peer review when determining if there is
consensus to merge a pull request (remember that discussions may have been
spread out over GitHub, mailing list and IRC discussions).
spread out over GitHub and Discord).

Code review is a burdensome but important part of the development process, and
as such, certain types of pull requests are rejected. In general, if the
Expand Down Expand Up @@ -374,7 +349,7 @@ mistakes could be very costly to the wider community. This includes refactoring
of consensus-critical code.

Where a patch set proposes to change the Bitcoin consensus, it must have been
discussed extensively on the mailing list and IRC, be accompanied by a widely
discussed extensively on Discord, be accompanied by a widely
discussed BIP and have a generally widely perceived technical consensus of being
a worthwhile change based on the judgement of the maintainers.

Expand All @@ -396,15 +371,14 @@ about:
that personally, though! Instead, take another critical look at what you are suggesting
and see if it: changes too much, is too broad, doesn't adhere to the
[developer notes](doc/developer-notes.md), is dangerous or insecure, is messily written, etc.
Identify and address any of the issues you find. Then ask e.g. on IRC if someone could give
their opinion on the concept itself.
Identify and address any of the issues you find. Then ask on Discord if someone could give their opinion on the concept itself.
- It may be because your code is too complex for all but a few people, and those people
may not have realized your pull request even exists. A great way to find people who
are qualified and care about the code you are touching is the
[Git Blame feature](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/tracking-changes-in-a-file). Simply
look up who last modified the code you are changing and see if you can find
them and give them a nudge. Don't be incessant about the nudging, though.
- Finally, if all else fails, ask on IRC or elsewhere for someone to give your pull request
- Finally, if all else fails, ask on Discord for someone to give your pull request
a look. If you think you've been waiting for an unreasonably long time (say,
more than a month) for no particular reason (a few lines changed, etc.),
this is totally fine. Try to return the favor when someone else is asking
Expand Down