diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c23b25b..3bba2a5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,76 +1,116 @@ # How to contribute to a Stellar project -Your contributions to the [Stellar network](https://www.stellar.org/) will help improve the world’s -financial infrastructure, faster. +Your contributions to the [Stellar network](https://www.stellar.org/) will help +improve the world’s financial infrastructure. -We want to make it as easy as possible to contribute changes that help the Stellar network grow and -thrive. There are a few guidelines that we ask contributors to follow so that we can merge your -changes quickly. +We want to make it as easy as possible to contribute to Stellar in ways that +make the network grow and thrive. There are a few guidelines that we ask +contributors to follow so that we all work effectively together. -## Getting Started - -* Make sure you have a [GitHub account](https://github.com/signup/free). -* Create a GitHub issue for your contribution, assuming one does not already exist. - * Clearly describe the issue including steps to reproduce if it is a bug. -* Fork the repository on GitHub. - -### Minor Changes - -#### Documentation - -For small changes to comments and documentation, it is not -always necessary to create a new GitHub issue. In this case, it is -appropriate to start the first line of a commit with 'doc' instead of -an issue number. - -## Finding things to work on - -The first place to start is always looking over the current GitHub issues for the project you are -interested in contributing to. Issues marked with [help wanted][help-wanted] or are usually pretty -self-contained and a good place to get started. - -The Stellar Development Foundation also uses these same GitHub issues to keep track of what we are -working on. - -Before starting work on an issue it can be a good idea to communicate on the issue, discussing -what the solution might look like, and if it would make sense to contribute to it. - -Of course, feel free to create a new issue if you think something needs to be added or fixed. +> [!TIP] +> The Stellar network is open, decentralized, and programmable. Many ideas you +> may have can be built without changes to the projects hosted here. Want to +> contribute to Stellar? Build on Stellar! And share your feedback in the forums +> listed below. +To contribute to the work of maintaining the projects hosted here, the +biggest-impact contributions are participating in discussions, sharing new +ideas, reporting bugs, and sharing experience reports. -## Making Changes - -* Create a feature branch from where you want to base your work. - * This is usually the main (or master) branch. - * Please avoid working directly on the `main` (or `master`) branch. -* Make sure you have added the necessary tests for your changes and make sure all tests pass. - -## Submitting Changes - -* All content, comments, pull requests and other contributions must comply with the - [Stellar Code of Conduct][coc]. -* Push your changes to a topic branch in your fork of the repository. -* Submit a pull request to the repository in the Stellar - organization. - * Include a descriptive [commit message][commit-msg]. - * Changes contributed via pull request should focus on a single issue at a time. - * Rebase your local changes against the `main` branch. Resolve any conflicts that arise. - - -At this point you're waiting on us. We like to at least comment on pull requests within three -business days (typically, one business day). We may suggest some changes, improvements or -alternatives. - -# Additional Resources - -* [Explore our APIs](https://developers.stellar.org/docs) -* [Stellar Developer Discord](https://discord.com/invite/stellardev) - -This document is inspired by: +## Getting Started -* https://github.com/puppetlabs/puppet/blob/master/CONTRIBUTING.md -* https://github.com/thoughtbot/factory_girl_rails/blob/master/CONTRIBUTING.md -* https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md +- Make sure you have a [GitHub account](https://github.com/signup/free) +- Read the [Stellar Code of Conduct][coc], as all content, comments, pull + requests and other contributions must comply with it +- Create discussions at https://github.com/orgs/stellar/discussions with + problems and new ideas, or participate in existing discussions +- Create proposals at https://github.com/stellar/stellar-protocol after sharing + ideas in a discussion first +- Create GitHub issues for bugs and feature requests that target specific + projects + +## Reporting Bugs and Requesting Features + +First search for an existing issue and join a relevant discussion if an existing +issue is present. + +After confirming an issue does not already exist, create a GitHub issue with: + +- The concrete problem that needs solving. +- For bugs, include a minimal reproducer with the expected and actual behavior. +- Relevant alternatives, if any, and their tradeoffs. +- Verify everything reported before submitting. Do not submit speculative + findings or generated lists of possible issues. + +## Pull Requests + +Projects hosted here only accept pull requests for issues with the `help wanted` +label or if they indicate otherwise in their own contributing guidelines. +Unsolicited pull requests will be closed without an explanation and reported as +spam. + +Making changes requires deep architectural knowledge, a good understanding of +system constraints, and an idea about the project roadmap. Many Stellar projects +facilitate financial transactions or are dependencies to many other projects. +Correctness is critical and thoughtful evolution of behaviour and APIs is +paramount. Maintainer and reviewer time is limited. External contributors often +do not have the context required and reviewing takes the maintainers' focus away +from high-priority work that has already been discussed in discussion forums and +that the ecosystem is waiting on. + +Key things to keep in mind when creating a pull request: + +- Does the change narrowly address an open issue and have you been assigned? +- Does the change comply with the [Stellar Code of Conduct][coc]. +- Link the approved issue. + +## AI-Assisted Contributions + +The use of AI tools to improve productivity and the quality of contributions is +encouraged. AI assistance does not, however, change the responsibilities or +standards that apply to the human contributor. + +Maintainers are not obligated to review contributions that do not appear to meet +these standards and may close or reject them without performing the verification +that is the submitter's responsibility. + +Before exposing other community members to AI-assisted content, the human +submitter is responsible for: + +- **Reviewing and verifying all generated content**, including code, tests, code + comments, documentation, issues, pull-request descriptions, review feedback, + chat messages, forum posts, and other project or community communications. + Appropriate tests and checks must be performed where applicable. +- **Ensuring the contribution is correct, relevant, and appropriate for the + project**, including its security, reliability, maintainability, and adherence + to project standards. +- **Ensuring they have the right to submit the contribution**, including compliance + with applicable copyright, licensing, attribution, and other third-party + requirements. +- **Fully understanding the contribution**. The submitter must be able to explain it + in their own words, including its context, assumptions, design choices, + tradeoffs, and implications, and be able to answer questions and validate + changes arising during review. +- **Participating directly in review and community interactions**. AI may assist with + communication, but must not substitute for the submitter's own understanding, + judgment, or engagement. Contributors must not act merely as an intermediary + relaying content between other community members and an AI system. +- **Taking full responsibility for the contribution**. AI assistance does not + transfer responsibility for errors, omissions, security issues, licensing + problems, or other consequences to the AI tool or its provider. +- **Respecting the time and attention of other community members**. AI must not be + used to generate high volumes of low-quality or speculative contributions, or + to shift the burden of understanding, verification, debugging, or cleanup onto + reviewers and maintainers. + +**AI tools must not autonomously publish contributions or communications +to community channels without human review**; this includes code changes, issues, reviews, +chat messages, and forum posts. + +## Additional Resources + +- [Explore our APIs](https://developers.stellar.org/docs) +- [Stellar Developer Discord](https://discord.com/invite/stellardev) [help-wanted]: https://github.com/issues?q=is%3Aopen+is%3Aissue+user%3Astellar+label%3A%22help+wanted%22 [commit-msg]: https://github.com/erlang/otp/wiki/Writing-good-commit-messages