1# Contributing 2 3## Contents 4 5- [Introduction](#introduction) 6- [Code of Conduct](#code-of-conduct) 7- [Matrix Room](#matrix-room) 8- [Reporting Bugs and Suggesting Improvements](#reporting-bugs-and-suggesting-improvements) 9- [Contribution Workflow](#contribution-workflow) 10- [Quality Standards](#quality-standards) 11- [Release Process](#release-process) 12 13## Introduction 14 15Hello, and welcome to the contributing guide for Codespan! 16 17Codespan is mostly maintained in the spare time of contributors, 18so immediate reactions are not to be expected! 19By following this guide you'll make it easier for us to address your issues or incorporate your contributions. 20 21We look forward to working with you! 22 23## Code of Conduct 24 25Please note that this project is released with a [Code of Conduct](./CODE_OF_CONDUCT.md). 26By participating in this project you agree to abide by its terms. 27 28## Matrix Room 29 30Joining the matrix room at [#codespan:matrix.org][codespan-matrix] is a good way to get in touch with the developers and community. 31 32[codespan-matrix]: https://app.element.io/#/room/#codespan:matrix.org 33 34## Reporting Bugs and Suggesting Improvements 35 36Bugs (unwanted behaviour) and suggested improvements are tracked as [GitHub issues][github-issues]. 37Before reporting an issue, please check the following points: 38 391. The issue is caused by `codespan-reporting` itself and not by how it is used. 40 Have a look at the documentation if you are not sure. 41 If the documentation is not helpful, you can contact the developers at the above matrix chat address or make an issue. 421. Your issue has not already been reported by someone else. 43 Please look through the open issues in the [issue tracker][github-issues]. 44 45When reporting an issue, please add as much relevant information as possible. 46This will help developers and maintainers to resolve your issue. Some things you might consider: 47 48* Use a descriptive title. 49* Describe how a problem can be reproduced. Ideally give a minimal example. 50* Explain what exactly is the problem and what you expect instead. If it is related to rendering, add screenshots or other illustrations. 51 52[github-issues]: https://github.com/brendanzab/codespan/issues 53 54## Contribution Workflow 55 56Follow these steps to contribute to the project: 57 581. Make a fork of the [codespan repository][codespan-repo]. 591. Within your fork, create a branch for your contribution. Use a meaningful name. 601. Create your contribution, meeting all [contribution quality standards](#quality-standards). 611. Ensure all the tests pass (`cargo test`). 621. [Create a pull request][create-a-pr] against the `master` branch of the repository. 631. Once the pull request is reviewed and CI passes, it will be merged. 64 65[codespan-repo]: https://github.com/brendanzab/codespan 66[create-a-pr]: https://help.github.com/articles/creating-a-pull-request-from-a-fork/ 67 68## Quality Standards 69 70Most quality and style standards are checked automatically by the CI build. 71Contributions should: 72 73- Separate each **logical change** into its own commit. 74- Include tests for any new functionality and fixed issues in your pull request. 75- Update the changelogs with any added, removed, changed, or fixed functionality. 76- Document public functions. 77- Format code with `cargo fmt`. 78- Avoid adding `unsafe` code. 79 If it is necessary, provide an explanatory comment on any `unsafe` block explaining its rationale and why it's safe. 80- Add a descriptive message for each commit. 81 Follow [these commit message guidelines][commit-messages]. 82- Document your pull requests. 83 Include the reasoning behind each change, and the testing done. 84 85[commit-messages]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html 86 87## Release Process 88 891. Bump the version numbers of each crate appropriately. 901. Update the changelogs with the new version ranges. 911. Create a new PR for the release, and if it passes CI merge it. 921. Create a new tag for the release, pointing to the merge commit. 931. Run the following commands in order from the root of the repository. 94 Note that doing this too quickly may result in an error, 95 due to a server-side delay in crate publishing: 96 ``` 97 cd codespan-reporting && cargo publish; cd .. 98 cd codespan && cargo publish; cd .. 99 cd codespan-lsp && cargo publish; cd .. 100 ``` 101