You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 7c5fe91
Browse filesBrowse the repository at this point in the historyBrowse files
CONTRIBUTING.md was inherited from Bitcoin Core and named paths and
workflows this project doesn't have. Keep Core's structure and review
philosophy, and adapt the parts that differ: the editable `.[dev]`
install (quoted so it works in POSIX shells, PowerShell and cmd), the
CI checks, security reporting, the AI policy, licensing and
third-party attribution, and the maintainer-authorized review-size
budgets.
Refs #38
Claude-Session: https://claude.ai/code/session_01Q1TNm1YeYW8K9W2eBvxmCD
If you use AI tools while contributing, please read and follow the [AI
14
-
policy](/doc/AI_POLICY.md).
14
+
policy](docs/developer/AI_POLICY.md).
15
15
16
16
In-depth reviewing and testing are the bottleneck of the project, and are the
17
17
most effective way anyone can start to contribute. It will teach you much more
18
18
about the code and process than opening pull requests, and may help you uncover
19
19
related issues and follow-ups to contribute code for. Please refer to the [peer
20
20
review](#peer-review) section below.
21
21
22
-
Before you start contributing, familiarize yourself with the build system and
23
-
tests. Refer to the documentation in the repository on how to build the project
24
-
and how to run the unit tests, functional tests, and fuzz tests.
22
+
Before you start contributing, familiarize yourself with the [developer API
23
+
guide](docs/developer/api.md), [security model](docs/security/model.md), and
24
+
[user guide](docs/user/guide.md).
25
+
26
+
The supported development setup uses Python 3.10 through 3.15. From the
27
+
repository root:
28
+
29
+
python -m venv .venv
30
+
source .venv/bin/activate
31
+
python -m pip install --upgrade pip
32
+
python -m pip install -e ".[dev]"
33
+
python -m pip check
34
+
python -m pytest -q
35
+
36
+
On Windows, activate with `.\.venv\Scripts\Activate.ps1` in PowerShell or
37
+
`.venv\Scripts\activate.bat` in Command Prompt. The `.[dev]` extra installs the
38
+
test and development tools. If the suite cannot collect after these steps,
39
+
include the Python version and full error in the report.
40
+
41
+
CI also runs these checks on selected jobs:
42
+
43
+
python -O -m pytest -q
44
+
python tools/verify_correction_constants.py
45
+
python -m mypy src/codex32
46
+
python -m ruff check .
47
+
python -m ruff format --check .
48
+
python tools/differential_correction.py --verify
49
+
50
+
For packaging or release changes, also build and check the distributions:
51
+
52
+
python -m build
53
+
python -m twine check dist/*
54
+
55
+
For changes to Bitcoin Core wallet behavior, run the focused Core fixture
56
+
workflow as well; see `.github/workflows/bitcoin-core-fixtures.yml` for the
57
+
pinned binary and invocation. Do not use funded wallets for testing.
25
58
26
59
Communication Channels
27
60
----------------------
@@ -49,10 +82,17 @@ To contribute a patch, the workflow is as follows:
49
82
1. Create topic branch
50
83
1. Commit patches
51
84
52
-
The master branch for all monotree repositories is identical.
85
+
The supported API and review boundaries in the [developer API
86
+
guide](docs/developer/api.md) must be followed. Security-sensitive changes must
87
+
also follow [SECURITY.md](SECURITY.md), including its private-reporting and
88
+
synthetic-test-material requirements, and the [security
89
+
invariants](docs/security/invariants.md).
53
90
54
-
The project coding conventions in the [developer notes](doc/developer-notes.md)
55
-
must be followed.
91
+
For v1, the installed library must remain below 5,200 logical review lines. GUI
92
+
work uses a separate 2,250-line budget once it is part of the candidate.
93
+
Changing either budget requires explicit maintainer review and authorization,
94
+
together with matching documentation and enforcement. Do not take unrelated
95
+
refactors solely to create line-count headroom.
56
96
57
97
### Committing Patches
58
98
@@ -62,13 +102,11 @@ fixes or code moves with actual code changes.
62
102
63
103
Make sure each individual commit is hygienic: that it builds successfully on its
64
104
own without warnings, errors, regressions, or test failures.
65
-
See the [developer notes](doc/developer-notes.md#commit-structure-for-tests)
66
-
for guidance on where test coverage belongs in a commit stack.
67
105
68
106
Commit messages should be verbose by default consisting of a short subject line
69
107
(50 chars max), a blank line and detailed explanatory text as separate
70
-
paragraph(s), unless the title alone is self-explanatory (like "Correct typo
71
-
in init.cpp") in which case a single title line is sufficient. Commit messages should be
108
+
paragraph(s), unless the title alone is self-explanatory (like "Correct typo")
109
+
in which case a single title line is sufficient. Commit messages should be
72
110
helpful to people reading your code in the future, so explain the reasoning for
73
111
your decisions. Further explanation [here](https://cbea.ms/git-commit/).
74
112
@@ -100,11 +138,16 @@ any users mentioned in the description will be annoyingly notified each time a
100
138
fork copies the merge. Instead, make any username mentions in a subsequent
101
139
comment to the PR.
102
140
141
+
State which automated checks and manual tests you ran. Where a bug is fixed,
142
+
include a regression test when practical. Update the affected user or developer
143
+
documentation when a contract changes.
144
+
103
145
### Work in Progress Changes and Requests for Comments
104
146
105
147
If a pull request is not to be considered for merging (yet), please
106
148
prefix the title with [WIP] or use [Tasks Lists](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#task-lists)
107
-
in the body of the pull request to indicate tasks are pending.
149
+
in the body of the pull request to indicate tasks are pending. A draft pull
150
+
request is also appropriate for changes that are not ready for review.
108
151
109
152
### Address Feedback
110
153
@@ -117,6 +160,10 @@ merged. You may update the code or reject the feedback if you do not agree with
117
160
it, but you should express so in a reply. If there is outstanding feedback and
118
161
you are not actively working on it, your pull request may be closed.
119
162
163
+
If you change a reviewed commit, say what changed and rerun the relevant checks.
164
+
Do not repeatedly request automated reviews when a quota limit or a non-blocking
165
+
stylistic disagreement is the only remaining issue.
166
+
120
167
Please refer to the [peer review](#peer-review) section below for more details.
121
168
122
169
### Squashing Commits
@@ -131,7 +178,8 @@ before it will be reviewed. The basic squashing workflow is shown below.
131
178
# Set commits (except the one in the first line) from 'pick' to 'squash', save and quit.
132
179
# On the next screen, edit/refine commit messages.
133
180
# Save and quit.
134
-
git push -f # (force push to GitHub)
181
+
git push --force-with-lease # (force push to GitHub, refusing to clobber
182
+
# commits you have not fetched)
135
183
136
184
Please update the resulting commit message, if needed. It should read as a
137
185
coherent message. In most cases, this means not just listing the interim
@@ -153,18 +201,24 @@ pull request to pull request.
153
201
154
202
When a pull request conflicts with the target branch, you may be asked to rebase it on top of the current target branch.
155
203
156
-
git fetch # Fetch the latest upstream commit
157
-
git rebase FETCH_HEAD # Rebuild commits on top of the new base
204
+
If you cloned your fork normally, configure the project repository once:
0 commit comments