diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9bb2ef87a..bd38126b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,155 @@ -Specter-desktop is an Open Source Project under the MIT-License and everyone is invited to contribute to it. +# Contributing to Specter Desktop -We haven't created many explicit processes and rely on the best practices of Open Source projects. If you want to contribute, fork the project and create a PR. +Specter Desktop is an Open Source Project under the MIT License and everyone is invited to contribute to it. -If it's necessary to add processes, we'll probably looking into Pieter Hintjens' [Social Architecture](https://hintjens.gitbooks.io/social-architecture/content/) and specifically the C4 process. Pieter is explicitly mentioning two roles: Contributors and maintainers. +We haven't created many explicit processes and rely on the best practices of Open Source projects. If you want to contribute, fork the project and create a PR. -Thank you very much to all our [Contributors](https://github.com/cryptoadvance/specter-desktop/graphs/contributors). -See also the Contributors to each specific release in the release-notes. +## Table of Contents -The maintainers are the ones who are able to merge PRs and create tags/releases. They are listed as "authors" in setup.py. +- [How to Contribute](#how-to-contribute) +- [Development Setup](#development-setup) +- [Code Standards](#code-standards) +- [Testing](#testing) +- [Finding Help](#finding-help) +- [Contributors and Maintainers](#contributors-and-maintainers) -For practical considerations of a dev-setup, please have a look in the [development.md](docs/development.md). If you need support, join our [Telegram group](https://t.me/spectersupport). +## How to Contribute + +To contribute code: + +1. **Fork the repository** on GitHub +2. **Create a branch** from `master` (or the relevant branch) + ```bash + git checkout -b your-feature-branch + ``` + +3. **Make your changes** + - Follow our [Code Standards](#code-standards) + - Write or update tests as needed + - Update documentation if necessary + +4. **Test your changes** + - Run the test suite (see [Testing](#testing)) + - Ensure all tests pass + +5. **Commit your changes** + - Write clear, descriptive commit messages + - If addressing an issue, reference it in your commit message: `Fixes #123` or `Closes #123` + +6. **Push to your fork** and create a Pull Request + +## Development Setup + +For detailed development setup instructions, see [docs/development.md](docs/development.md). + +Quick start: + +1. **Install dependencies** (see [docs/development.md](docs/development.md) for platform-specific instructions) + +2. **Set up virtual environment** + ```sh + git clone https://github.com/cryptoadvance/specter-desktop.git + cd specter-desktop + pip3 install virtualenv + virtualenv --python=python3 .env + source .env/bin/activate # On Windows: .env\Scripts\activate + pip3 install -r requirements.txt --require-hashes + pip3 install -e . + ``` + +3. **Run the development server** + ```sh + python3 -m cryptoadvance.specter server --config DevelopmentConfig --debug + ``` + Specter will be available at http://127.0.0.1:25441/ + +**Note**: Specter currently supports Python 3.9 and 3.10. + +## Code Standards + +### Python Code Style + +- **Use Black** for code formatting. We have a pre-commit hook to automate this: + ```bash + pre-commit install + ``` + This will automatically format your code before commits. + +### Frontend + +- We prefer plain JavaScript over frameworks +- Use Material Icons from https://material.io/resources/icons/?style=baseline +- Color scheme: + - Orange: `#F5A623` + - Blue: `#4A90E2` + +### Dependencies + +- **Minimize dependencies** - We're security-conscious and prefer fewer dependencies +- If you update `requirements.in`, generate the new `requirements.txt`: + ```sh + pip-compile --generate-hashes requirements.in + ``` + +## Testing + +We use two testing frameworks: + +### Backend Tests (pytest) + +Run the test suite: +```bash +# Run all tests +pytest + +# Run tests excluding slow ones +pytest -m "not slow" + +# Run specific test file +pytest tests/test_specter.py + +# Run specific test +pytest tests/test_specter.py::test_specter +``` + +**Note**: You need bitcoind for tests. See [docs/development.md](docs/development.md#how-to-run-the-tests) for setup instructions. + +### Frontend Tests (Cypress) + +Run Cypress tests: +```bash +# Run all Cypress tests +./utils/test-cypress.sh run + +# Open Cypress app for interactive testing +./utils/test-cypress.sh open + +# Run specific test with snapshot +./utils/test-cypress.sh snapshot spec_wallet_utxo.js +./utils/test-cypress.sh run spec_wallet_utxo.js +``` + +For more details, see [docs/cypress-testing.md](docs/cypress-testing.md). + +## Finding Help + +- **Documentation**: Check [docs/development.md](docs/development.md) for development setup +- **FAQ**: See [docs/faq.md](docs/faq.md) for common questions +- **Telegram**: Join our [Telegram support group](https://t.me/spectersupport) for real-time help +- **GitHub Issues**: Search existing issues or create a new one + +## Contributors and Maintainers + +### Contributors + +Thank you very much to all our [Contributors](https://github.com/cryptoadvance/specter-desktop/graphs/contributors). See also the contributors to each specific release in the release-notes. + +### Maintainers + +Maintainers are the ones who can merge PRs and create tags/releases. They are listed as "authors" in `pyproject.toml` (and `setup.py`). + +If it's necessary to add more formal processes, we'll probably look into Pieter Hintjens' [Social Architecture](https://hintjens.gitbooks.io/social-architecture/content/) and specifically the C4 process. Pieter explicitly mentions two roles: Contributors and Maintainers. + +--- + +Thank you for contributing to Specter Desktop! Your contributions help make Bitcoin more accessible and secure for everyone.