Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
147 lines (96 loc) · 6.4 KB

CONTRIBUTING.md

File metadata and controls

147 lines (96 loc) · 6.4 KB

Contributing

Welcome to Payjoin Dev Kit (PDK).

This monorepo is home to the most widely-adopted Payjoin software.

As such, contributions are greatly valued, necessary, and impactful: whether it's reporting issues, writing documentation, or contributing code, we'd love your help!

Communication Channels

Most discussion about Payjoin research and development happens on Discord, or in Github issues or pull requests.

Issues

Using and testing Payjoin Dev Kit is an effective way for new contributors to both learn and provide value. If you find a bug, incorrect or unclear documentation, or have any other problem, consider creating an issue. Before doing so, please search through existing issues to see if your problem has already been addressed or is actively being discussed. If you can, provide a fully reproducible example or the steps we can use to reproduce the issue to speed up the debugging process.

Documentation

Good documentation is essential to understanding what PDK does and how to use it. Since PDK seeks to raise Payjoin adoption by making it easy for developers to integrate it into their wallets, providing clear and complete documentation is critical. Good documentation is also invaluable to new contributors ramping up quickly. If you find something hard to understand or difficult to figure out how to use from the documentation, it's a sign they could be improved. To contribute to the documentation please fork the repository, make changes there, and then submit a pull request.

Code

Getting Started

If you're looking for somewhere to start contributing code changes, see the good first issue list. If you intend to start working on an issue, please leave a comment stating your intent.

To contribute a code change:

  1. Fork the repository.
  2. Create a topic branch.
  3. Commit changes.

Commits

The git repository is our source of truth for development history. Therefore the commit history is the most important communication artifact we produce. Commit messages must follow the seven rules in this guide by cbeams.

Every commit should be hygenic and pass CI. This means tests, linting, and formatting should pass without issues on each commit. Below is a git hook you may choose to add to .git/hooks/pre-commit in your local repository to perform these checks before each commit:

#!/usr/bin/env bash
set -euo pipefail

# -------- 1. Rustfmt --------
echo "▶  cargo fmt --check"
cargo fmt --all -- --check

# -------- 2.1 Project-specific linter --------
echo "▶  ./contrib/lint.sh"
./contrib/lint.sh

# -------- 2.2 Documentation builder --------
echo '▶  RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features --document-private-items'
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features --document-private-items

# -------- 3. Fast local test suite --------
echo "▶  ./contrib/test_local.sh"
./contrib/test_local.sh

# -------- 4. lock file verification --------
changed_tomls=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '(^|/)Cargo\.toml$' || true)

if [ -n "$changed_tomls" ]; then
    echo "▶  Checking if lockfiles need updating…"
    ./contrib/update-lock-files.sh
    stale_locks=$(git diff --name-only -- Cargo-minimal.lock Cargo-recent.lock)
    if [ -n "$stale_locks" ]; then
        git checkout -- Cargo-minimal.lock Cargo-recent.lock
        echo "pre-commit: Cargo.toml changed and lockfiles are stale!"
        echo "Stale lockfiles:"
        echo "$stale_locks"
        echo "Run './contrib/update-lock-files.sh' and stage the lockfiles."
        exit 1
    fi
fi

echo "✓  Pre-commit hook passed"

AI Assistance Notice

Important

If you are using any kind of AI assistance to contribute it must be disclosed in the pull request.

If you are using any kind of AI assistance while contributing, this must be disclosed in the pull request, along with the extent to which AI assistance was used (e.g. docs only vs. code generation). If PR body or comments are being generated by an AI, disclose that as well. As a small exception, trivial tab-completion doesn't need to be disclosed, so long as it is limited to single keywords or short phrases.

An example disclosure:

This PR was written primarily by Claude Code.

Or a more detailed disclosure:

I consulted ChatGPT to understand the codebase but the solution was fully authored manually by myself.

Failure to disclose this is impolite to the human operators on the other end of the pull request, and it also makes it difficult to determine how much scrutiny to apply to the contribution. Please be respectful to maintainers and disclose AI assistance so that they may help you effectively contribute.

Nix Development Shells

Where nix is available (NixOS or otherwise), development shells are provided.

The default shell uses rust nightly, and can be activated manually using nix develop in the project root, or automatically with direnv.

To use the minimal supported version, use nix develop .#msrv. .#stable is also provided.

Testing

We test a few different features combinations in CI. To run all of the combinations locally run contrib/test.sh.

If you are adding a new feature please add tests for it.

Upgrading dependencies

If your change requires a dependency to be upgraded you must please run contrib/update-lock-files.sh before submitting any changes.

Code Formatting

We use the nightly Rust formatter for this project. Please run rustfmt using the nightly toolchain before submitting any changes.

Linting

We use clippy for linting. Please run contrib/lint.sh using the nightly toolchain before submitting any changes.