This document is intended for those whom wish to contribute to Agora, in the form of submitting issues or writing pull requests (PR). Thank you! The Agora core team is delighted to have community members contribute to our project.
Before making any form of contribution, it is advised that one familiarises themselves with the existing documentation. This will enable the contributor to submit better, more informed issues and will potentially aid a developer in writing PRs.
Please follow the Git policy when contributing to this project.
This document will make reference to the Agora core team. These are the people who work on Agora professionally and will be responsible for maintaining the project in its open source life. They include:
An issue is a post on the Agora Issues page. An issue may pertain to:
- A bug.
- A desired feature.
- A question one has that is not covered within documentation.
Before submitting an issue, please check that the same issue has not already been provided by another contributor. Such an issue could be open (unresolved) or closed (considered resolved). If it is open, please comment with your perspective on the issue. If it is closed, please read-through what has been posted on the issue page. If you believe the issue is still unresolved, feel free to re-open it along with a post explaining your reasons for doing so.
If your issue has not been submitted hitherto, please submit a new issue. To assist the Agora community please provide as much detail as you feel is relevant. For bugs, please include instructions on how to reproduce the issue and provide any terminal outputs. Please remember to tag your issue with GitHub's labelling system.
Top-tier issues include a minimal reproducible example. This should take the form of a public GitHub repository containing only the code required to reproduce the issue. Alongside a link to such a repository, please detail steps on how a maintainer may recreate the issue on their system.
If you wish to work to resolve the issue, the Agora team would invite you to submit a PR.
Only those within the core Agora team may contribute work to the project directly. If you wish to work on the project, you must fork the repository and submit your changes to your fork. Instructions for getting started with the project may be found in the README. Once the work on your fork is completed, you may submit a PR here.
If your PR fixes an issue that isn't a very obvious bug, or has not previously been discussed, please write an issue pertaining to the problem that your PR would solve. Read this document's section on Issues and pay particular heed to the paragraph asking contributors to look for pre-existing issues. The prior experiences of existing contributors could save you a significant amount of time and effort. It is possible that a number of issues could be solved by your PR. Please reference any issues that would be ameliorated by your PR - including your own issue, if you have written one - clearly. Please label your PR using GitHub's tagging feature. Please state plainly:
- What your PR achieves.
- How your PR works.
- What your PR changes.
- Any aspects of your work that you believe merit especially careful review.
Contributors should expect that if their work is insufficiently documented (either on GitHub or within the codebase) that their PR will not be reviewed by core Agora team members. Contributors should expect that an Agora maintainer may offer constructive feedback and request changes to be made, prior to the PR being incorporated into the project.
Agora utilises Plutarch and your work must be written with Plutarch, when appropriate. Plutarch can prove complicated but the documentation is extensive. We would encourage you to dive deeply into the documentation, whilst stating that Plutarch's Tricks.md could prove particularly helpful.
For your PR to be merged it must pass the CI checks.
These can be run locally by running nix run .#ci. If you are making a PR through a fork of the repository, they might not be run in CI. When this is the case, please ensure the CI checks run fine locally before you request a review.
Agora follows strict standards to increase consistency, to minimize the impact of legacy, to properly use automated tools, and more. The standards document can be found here.
It is worth noting that the codebase is not the only aspect of the project that it is worth contributing to. In the event that one finds the docs unsatisfactory, the Agora team would welcome receiving any issues describing your reservations or PRs pertaining to documentation.
Many thanks for reading. The Agora core team is delighted to be able to share the project with the Cardano community and we are thrilled by the prospect of collaborating with you all on improving our work.