diff options
| -rw-r--r-- | .github/contribute.md | 76 | ||||
| -rw-r--r-- | .github/support.md | 46 | ||||
| -rw-r--r-- | readme.md | 9 |
3 files changed, 126 insertions, 5 deletions
diff --git a/.github/contribute.md b/.github/contribute.md new file mode 100644 index 0000000..0972827 --- /dev/null +++ b/.github/contribute.md @@ -0,0 +1,76 @@ +# Contribute + +This article explains how to contribute. +Please read through the following guidelines. + +## Contributions + +There are several ways to contribute, not just by writing code. +See [Support][] if you have questions. + +### Financial support + +You can help financially. +See [Sponsor][] for more info. + +### Improve docs + +As a user you’re perfect to help improve the docs. +Typo corrections, error fixes, better explanations, new examples, etcetera. + +### Improve issues + +Some issues lack information, aren’t reproducible, or are just incorrect. +You can help by trying to make them easier to resolve. +Existing issues might benefit from your unique experience or opinions. + +### Write code + +Code contributions are very welcome too. +It’s probably a good idea to first post a question or open an issue to report a +bug or suggest a new feature before creating a pull request. + +## Submitting an issue + +- the issue tracker is for issues, discussions are for for questions +- search the issue tracker (including closed issues) before opening a new + issue +- ensure you’re using the latest versions of packages and other tools +- use a clear and descriptive title +- include as much information as possible: steps to reproduce the issue, + error message, version, operating system, etcetera +- the more time you put into an issue, the better help you can get +- the best issue report is a [failing test][unit-test] proving it + +## Submitting a pull request + +- run `cargo fmt` and `cargo test` locally to format and test your changes +- non-trivial changes are often best discussed in an issue first, to prevent + you from doing unnecessary work +- for ambitious tasks, you should try to get your work in front of the + community for feedback as soon as possible +- new features should be accompanied by tests and documentation +- don’t include unrelated changes +- write a convincing description of why your pull request should land: + it’s your job to be convincing + +## Resources + +- [how to contribute to open source](https://opensource.guide/how-to-contribute/) +- [making your first contribution](https://medium.com/@vadimdemedes/making-your-first-contribution-de6576ddb190) +- [using pull requests](https://help.github.com/articles/about-pull-requests/) +- [GitHub help](https://help.github.com) + +## License + +[CC-BY-4.0][license] © [Titus Wormer][author] + +<!-- Definitions --> + +[license]: https://creativecommons.org/licenses/by/4.0/ +[author]: https://wooorm.com +[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md +[unit-test]: https://twitter.com/sindresorhus/status/579306280495357953 +[support]: support.md +[collective]: https://opencollective.com/unified +[sponsor]: https://github.com/wooorm/micromark-rs/#sponsor diff --git a/.github/support.md b/.github/support.md new file mode 100644 index 0000000..7fd182d --- /dev/null +++ b/.github/support.md @@ -0,0 +1,46 @@ +# Support + +This article explains how and where to get help. +Please read through the following guidelines. + +## Asking quality questions + +Questions can go to [GitHub discussions][chat]. + +Help us help you! +Spend time framing questions and add links and resources. +Spending the extra time up front helps save everyone time in the long run. +Here are some tips: + +- see [this article on _How do I ask a good question_][how-to-ask] for help +- [talk to a duck][rubberduck]! +- don’t fall for the [XY problem][xy] +- search to find out if a similar question has been asked +- try to define what you need help with: + - is there something in particular you want to do? + - what problem are you encountering and what steps have you taken to try + and fix it? + - is there a concept you don’t understand? +- provide sample code, if possible +- screenshots can help, but if there’s important text such as code or error + messages in them, please also provide those as text +- the more time you put into asking your question, the better we can help you + +## Contributions + +See [`contributing.md`][contributing] on how to contribute. + +## License + +[CC-BY-4.0][license] © [Titus Wormer][author] + +<!-- Definitions --> + +[license]: https://creativecommons.org/licenses/by/4.0/ +[author]: https://wooorm.com +[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md +[rubberduck]: https://rubberduckdebugging.com +[xy]: https://meta.stackexchange.com/questions/66377/what-is-the-xy-problem/66378#66378 +[chat]: https://github.com/remarkjs/remark/discussions +[contributing]: contributing.md +[how-to-ask]: https://stackoverflow.com/help/how-to-ask @@ -301,11 +301,8 @@ For more information on markdown sanitation, see ### Contribute -> 🚧 **To do**. - -<!-- To do: contrib. --> -<!-- See [`contributing.md`][contributing] for ways to get started. -See [`support.md`][support] for ways to get help. --> +See [`contributing.md`][contributing] for ways to help. +See [`support.md`][support] for ways to get help. <!-- To do: CoC. --> @@ -359,3 +356,5 @@ Support this effort and give back by sponsoring: [security]: #security [test]: #test [comparison]: #comparison +[contributing]: .github/contribute.md +[support]: .github/support.md |