Repository navigation
Package public backend contributor setup on sprint #7030
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.
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
antuz123
wants to merge
16
commits into
sprint
Choose a base branch
from
codex/r3-public-contributor-sprint
base: sprint
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
16 commits
Select commit
Hold shift + click to select a range
ef0d4d8
Package public backend contributor setup for sprint
antuz123 fb2dc41
Document shared sprint and release branch flow
antuz123 cc3f16f
Document Copilot triage and product signoff
antuz123 c80b4e7
Address Copilot findings in public contributor bootstrap
antuz123 2214d58
Record product signoff separately from developer review
antuz123 90d2e24
Request Ben and Utkarsh as sprint code owners
antuz123 934f712
Include Parsh in developer review requests
antuz123 3c8e745
Merge remote-tracking branch 'origin/sprint' into codex/r3-public-con…
antuz123 4c5e335
Verify revisioned backups with audited public backend sources
antuz123 19e079a
Check stale backup revisions after content restoration
antuz123 1fab43c
Address contributor review findings and verify 2FA rejection
antuz123 b39b0a1
Complete contributor setup docs and symlink integrity coverage
antuz123 2ec2026
Remove private backend revision IDs from public verification history
antuz123 9c66b35
Pin Relay signer-map cleanup for public contributor setup
antuz123 ce2972b
test: make Electrum suites deterministic for contributors
antuz123 5820845
docs: align contributor install with sprint lock state
antuz123 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| # Request the three developers for all changes; one approval is required. | ||
| * @ben-kaufman @cakesoft-utkarsh @Parsh | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| ## Problem and change | ||
|
|
||
| <!-- Explain the problem, the resulting behavior and what is outside this PR. --> | ||
|
|
||
| Issue: | ||
| OpenSpec change / archived proposal: | ||
| Target branch: | ||
|
|
||
| ## Test results | ||
|
|
||
| <!-- Include commands, platform/device and evidence. Mark unavailable checks as | ||
| not run or blocked. Manual verification is distinct from automated passes. --> | ||
|
|
||
| | Check / scenario | Platform | Passed / failed / blocked / not run | Evidence or reason | | ||
| | --- | --- | --- | --- | | ||
| | | | | | | ||
|
|
||
| ## Review considerations | ||
|
|
||
| <!-- Describe any security/privacy, storage/migration, network, dependency or | ||
| hardware impact; use "none" where appropriate. State any known limitations. | ||
| Report suspected vulnerabilities privately per SECURITY.md, not in this PR. --> | ||
|
|
||
| - [ ] The diff excludes local secrets, wallet data and generated build/dependency files. | ||
| - [ ] Test failures and untested behavior are recorded above. | ||
| - [ ] The issue/spec and implementation describe the same scope. | ||
|
|
||
| Keeper maintainers own security review, acceptance, merging and official releases. | ||
| Passing checks does not constitute approval. | ||
|
|
||
| ## Signoff | ||
|
|
||
| - Copilot review findings: <!-- Addressed, explained, or pending. Maintainer checks the actual comments. --> | ||
| - Developer approval: <!-- One approval required for sprint PRs. --> | ||
| - Product owner signoff: <!-- Link the owner's PR comment for product behavior, UX, or copy changes; otherwise state not applicable. --> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| name: Public backend setup | ||
|
|
||
| on: | ||
| push: | ||
| branches: [sprint, main] | ||
| paths: | ||
| - 'dev/local-backend/**' | ||
| - '.github/workflows/public-backend.yml' | ||
| pull_request: | ||
| branches: [sprint, main] | ||
| paths: | ||
| - 'dev/local-backend/**' | ||
| - '.github/workflows/public-backend.yml' | ||
| workflow_dispatch: | ||
|
|
||
| permissions: | ||
| contents: read | ||
|
|
||
| concurrency: | ||
| group: public-backend-${{ github.event.pull_request.number || github.ref }} | ||
| cancel-in-progress: true | ||
|
|
||
| jobs: | ||
| signing: | ||
| name: Public SigningServer adapter | ||
| runs-on: ubuntu-latest | ||
| timeout-minutes: 20 | ||
| steps: | ||
| - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 | ||
| with: | ||
| persist-credentials: false | ||
| - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 | ||
| with: | ||
| node-version: '22' | ||
| - run: ./dev/local-backend/dev prepare-signing | ||
| - run: npm ci --ignore-scripts | ||
| working-directory: dev/local-backend/.sources/signing | ||
| - run: npm run compile | ||
| working-directory: dev/local-backend/.sources/signing | ||
| - run: npm test | ||
| working-directory: dev/local-backend/.sources/signing | ||
|
|
||
| backend: | ||
| name: Local backend and bootstrap | ||
| runs-on: ubuntu-latest | ||
| timeout-minutes: 25 | ||
| steps: | ||
| - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 | ||
| with: | ||
| persist-credentials: false | ||
| - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 | ||
| with: | ||
| python-version: '3.9' | ||
| - run: python3 -B -m unittest discover -s dev/local-backend -p 'test_*.py' | ||
| - run: ./dev/local-backend/dev up | ||
| - run: ./dev/local-backend/verify-local.sh --persistence --boundaries | ||
| - name: Stop containers and retain volumes | ||
| if: always() | ||
| run: ./dev/local-backend/dev stop |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,128 @@ | ||
| # Contributing to Bitcoin Keeper | ||
|
|
||
| Contributions are welcome through forks and pull requests. Keeper | ||
| maintainers are responsible for code and security review, assessing privacy risks, | ||
| deciding whether to accept changes, and controlling merges and public releases. | ||
| Passing automated checks or submitting a working build does not constitute approval. | ||
|
|
||
| ## Set up a local workspace | ||
|
|
||
| Fork this repository on GitHub and clone your fork for contributions. You do not | ||
| need write access to the Keeper repository or production credentials. Follow the | ||
| [local development guide](dev/local-backend/README.md) for tool versions, Docker | ||
| backend setup, Android Studio/Xcode builds and troubleshooting. Docker runs the | ||
| backend; native SDKs and the mobile app run on your host. | ||
|
|
||
| The [SigningServer source](https://github.com/KeeperCommunity/SigningServer) is | ||
| public and can be cloned, installed, built, tested and contributed to on its own. | ||
| The full Docker app/backend setup uses the public | ||
| [Relay](https://github.com/KeeperCommunity/Relay) and SigningServer sources; | ||
| it requires no repository invitation. Optional private development resources | ||
| follow a separate [access process](dev/local-backend/ACCESS.md). Access approval | ||
| is separate from acceptance of contributed code. | ||
|
|
||
| The guide's [capability table](dev/local-backend/README.md#what-works-locally) lists | ||
| supported local flows and unavailable integrations. The | ||
| [verification record](dev/local-backend/VERIFICATION.md) distinguishes tested | ||
| behavior from failures and untested platforms. Start with disposable testnet | ||
| wallets. Store accounts, release signing keys and production backend access are | ||
| not prerequisites for contributing. | ||
|
|
||
| ## Develop a focused change | ||
|
|
||
| 1. Find an existing issue or describe the problem in a new issue. For a suspected | ||
| vulnerability, use the private process in [SECURITY.md](SECURITY.md) instead. | ||
| 2. Create a branch in your fork. Use the base branch associated with the issue; | ||
| if none is specified, use the repository's default development branch, | ||
| `sprint`. Do not assume a release tag includes every unreleased feature. | ||
| 3. Capture the change's scope and acceptance criteria using the repository's | ||
| OpenSpec workflow. The CLI is included in the locked development dependencies: | ||
|
|
||
| ```sh | ||
| yarn openspec new change your-change-name | ||
| yarn openspec status --change your-change-name | ||
| yarn openspec instructions proposal --change your-change-name | ||
| ``` | ||
|
|
||
| Follow the artifact instructions for proposal, specs, design and tasks. Read | ||
| [OpenSpec configuration](openspec/config.yaml); for UI changes, also read | ||
| [DESIGN.md](DESIGN.md). The repository's | ||
| [change-engineer workflow](.github/agents/change-engineer.agent.md) describes | ||
| planning, implementation and archiving. Respect any explicit repository-owner | ||
| restrictions on committing, pushing or publishing when using coding agents. | ||
| 4. Implement the agreed scope, reuse existing components and keep unrelated | ||
| formatting, dependency upgrades, feature reconciliation and version bumps out | ||
| of the change. Maintainers coordinate version numbers and the | ||
| [Android](android/fastlane/README.md) and [iOS](ios/fastlane/README.md) release | ||
| workflows separately from local development. | ||
|
|
||
| `sprint` is the shared integration branch. Maintainers may use a temporary | ||
| release branch while a specific app version is stabilized. Carry fixes made on | ||
| that branch back into `sprint` so the shared development line stays current; | ||
| then follow the reviewed `dev` to `main` release promotion used by the project. | ||
|
|
||
| For backend development, bootstrap creates ignored checkouts under | ||
| `dev/local-backend/.sources/`. Save backend work in a branch/patch and submit it to | ||
| the appropriate backend repository; an app PR does not include those ignored | ||
| edits. Changes to packaged adapters must update the corresponding SHA-256 entries | ||
| in `sources.lock.json` and be verified from freshly prepared sources. Do not | ||
| package a generated checkout, database or signing volume in a PR. | ||
|
|
||
| ## Test and report the result | ||
|
|
||
| Run checks relevant to the changed behavior. These commands run from the app root: | ||
|
|
||
| | Change | Checks | | ||
| | --- | --- | | ||
| | App logic | `yarn test --runInBand` (or the relevant Jest test paths) and `yarn lint` | | ||
| | User flow or native code | Build the affected development app and exercise the acceptance scenarios; use/update relevant Maestro flows under `flows/` | | ||
| | Local backend/bootstrap | `python3 -B -m unittest discover -s dev/local-backend -p 'test_*.py'` and `./dev/local-backend/dev verify` | | ||
| | Persistence or isolation | `./dev/local-backend/verify-local.sh --persistence --boundaries` on a disposable, otherwise idle Compose project | | ||
| | OpenSpec | `yarn openspec validate your-change-name --strict` | | ||
|
|
||
| Shared mobile changes should be checked on both Android and iOS. If a platform, | ||
| hardware device or integration is unavailable, say so; maintainers decide what | ||
| additional testing is required before acceptance. A local backend smoke test does | ||
| not validate recovery, transaction signing or every mobile feature. | ||
|
|
||
| Report the commands, commit, platform/device, actual results and relevant redacted | ||
| evidence. Keep **passed**, **failed/blocked** and **not run** separate. Describe | ||
| existing failures rather than hiding them or reporting an unexecuted check as a | ||
| pass. Screenshots can support manual verification but do not turn a failed | ||
| automated assertion into a passing automated test. | ||
|
|
||
| ## Submit and review | ||
|
|
||
| Open a pull request from your fork and complete the supplied template. Link the | ||
| issue and OpenSpec artifacts, explain the behavior change and provide the test | ||
| results. Review the diff before submission: exclude local environment files, | ||
| generated dependencies, databases, keys, wallet backups and signing credentials. | ||
| Use [SECURITY.md](SECURITY.md) for private vulnerability details. | ||
|
|
||
| Keeper maintainers review correctness, product fit, security/privacy, dependencies | ||
| and test evidence. They may request revisions or additional tests, and decide | ||
| whether a change is accepted. Only authorized maintainers merge and release | ||
| official builds. Contributors do not need release permissions to participate. | ||
|
|
||
| Copilot code review is requested automatically for pull requests targeting | ||
| `sprint`. Read its actual comments and check each claim against the changed code | ||
| and relevant tests. Fix valid findings or explain why a comment does not apply | ||
| before requesting final human review. One developer approval remains the code | ||
| review gate. GitHub requests Ben, Utkarsh, and Parsh when a PR is ready for review; | ||
| any one can provide that approval. For changes to product behavior, | ||
| UX, or copy, the product owner | ||
| records separate product signoff in the PR discussion. A PR author's product | ||
| signoff does not count as GitHub's required developer approval. | ||
|
|
||
| Some existing CI checks use maintainer-managed services or secrets. If a check is | ||
| unavailable on a fork PR, report it in the PR so maintainers can arrange review; | ||
| do not request production secrets or treat an unavailable check as passing. | ||
| This document defines review responsibilities; it does not claim that GitHub | ||
| branch protection or approval rules have been configured or verified. | ||
|
|
||
| GitHub runs app tests and separate public backend/bootstrap checks. The existing Electrum/wallet integration | ||
| tests use public testnet nodes and fee services; an internet connection is needed. | ||
| Coverage, where generated, measures the configured Electrum/wallet source | ||
| directories, not every app screen. SonarCloud analysis on the development branch | ||
| is deferred; passing tests are not a security analysis pass. See [CI notes](dev/local-backend/CI.md) | ||
| for the branch-specific checks, deferred analysis work and evidence limits. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| # Copy to .env only when changing the defaults. No secrets required. | ||
| COMPOSE_PROJECT_NAME=keeper-contributor | ||
| KEEPER_RELAY_PORT=3000 | ||
| KEEPER_CHANNEL_PORT=4002 | ||
| KEEPER_SIGNING_PORT=3003 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| .sources/ | ||
| .env | ||
| __pycache__/ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| # Optional private development resources | ||
|
|
||
| The public [app](https://github.com/KeeperCommunity/bitcoin-keeper), | ||
| [Relay](https://github.com/KeeperCommunity/Relay), and | ||
| [SigningServer](https://github.com/KeeperCommunity/SigningServer) can be cloned, | ||
| built, tested and contributed to without a Keeper invitation. The local Docker | ||
| setup in [README.md](README.md) uses only those public repositories and | ||
| disposable development identities. Production credentials are never needed. | ||
|
|
||
| Some assigned work may need separate private repositories, provider dashboards, | ||
| or test infrastructure. Ask the Keeper maintainer coordinating that work in your | ||
| existing private conversation. Include your GitHub username, task and the exact | ||
| resource needed. Do not post credentials or private access requests in a public | ||
| issue. If you do not have a maintainer contact, use the | ||
| [community contact](../../Readme.md#community) to reach one privately. | ||
|
|
||
| Maintainers review the work and grant only the needed permissions after checking | ||
| that the resource is ready to share. Approval covers the development access, not | ||
| every local command or proposed code change. Record invitation acceptance and | ||
| setup success in the internal development backlog. A contributor must use their | ||
| own GitHub identity; maintainers must not share personal tokens. | ||
|
|
||
| Security reports follow [SECURITY.md](../../SECURITY.md). Code acceptance, | ||
| merges, production access and releases remain separate maintainer decisions. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| # Contributor checks and analysis | ||
|
|
||
| ## Public backend CI | ||
|
|
||
| The app's local backend workflow pins the public | ||
| [Relay](https://github.com/KeeperCommunity/Relay) and | ||
| [SigningServer](https://github.com/KeeperCommunity/SigningServer). It requires no | ||
| private repository token or production credential. The default branch runs | ||
| `Public backend setup` for the packaged adapter, bootstrap and disposable API | ||
| checks. Earlier Linux backend runs failed while fetching the private Relay; | ||
| those historical runs do not establish the result for this public pin. | ||
| Code acceptance and releases remain maintainer decisions. | ||
|
|
||
| ## Active checks | ||
|
|
||
| The default branch's existing `Run Tests` workflow runs app tests. The new | ||
| `Public backend setup` workflow runs a separate public SigningServer adapter | ||
| fetch/install/compile/test job and full local backend bootstrap, API, | ||
| persistence and network-boundary checks. Neither job uses hosted credentials. | ||
| Pull requests are checked against their proposed merge with the target branch. | ||
| The development branch's `Contributor checks` workflow additionally publishes | ||
| app test coverage; its results are tracked with PR #7014. | ||
|
|
||
| Where generated, Jest's LCOV measures only the | ||
| Electrum/wallet directories listed in `jest.config.js`; this is not whole-app | ||
| coverage. Test success is evidence about the exercised cases, not a security | ||
| clearance. Maintainers retain security review and acceptance responsibility. | ||
|
|
||
| ## SonarCloud deferred on 26 September 2026 | ||
|
|
||
| The project owner chose to defer SonarCloud on the development branch. That job | ||
| was removed from its active workflow; app tests and an LCOV artifact remain there. `sonar-project.properties` is | ||
| retained for future restoration, including the report path and quality-gate wait | ||
| setting. No analysis or quality-gate pass is claimed, and no threshold has been | ||
| lowered. GitHub protection settings were not changed; if a required Sonar status | ||
| blocks merging, a maintainer must reconcile that setting with this decision. | ||
|
|
||
| Before deferral, PR #7014's original and updated scanners failed while retrieving | ||
| the pull request, before analysis. Public project metadata lists the repository | ||
| as `bithyve/bitcoin-keeper`, while this PR lives in | ||
| `KeeperCommunity/bitcoin-keeper`. This suggests a stale binding; an administrator | ||
| needs to verify the exact access/configuration problem when analysis is restored. | ||
|
|
||
| Deferred follow-up: inspect the project's Repository binding and GitHub app | ||
| access, confirm project/organization keys and the secret, restore a pinned scanner | ||
| that consumes LCOV and waits for its quality gate, then review the actual result. | ||
| Keep analyzer credentials away from fork code. See Sonar's | ||
| [repository binding instructions](https://docs.sonarsource.com/sonarqube-cloud/managing-your-projects/administering-your-projects/changing-binding). | ||
|
|
||
| The last existing `sprint` analysis (17 September, commit `1adf4f663`) reported a | ||
| failed quality gate: 0% new-code coverage, reliability rating C, 5.1% duplication | ||
| and 0% reviewed security hotspots, using a September 2024 previous-version | ||
| baseline. These are historical findings, not this PR's analysis. Deferral does | ||
| not resolve them or replace Keeper's review. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.