From d125cb5880838ff062965454cee3159ef1fc10f1 Mon Sep 17 00:00:00 2001 From: innovaker <66737976+innovaker@users.noreply.github.com> Date: Tue, 17 Nov 2020 12:58:58 +0000 Subject: [PATCH] refactor(docs): move contents of CONTRIBUTING.md into docs Improves discoverability. --- CONTRIBUTING.md | 122 ++---------------------------------- docs/docs/contributing.md | 126 ++++++++++++++++++++++++++++++++++++++ docs/sidebars.js | 1 + 3 files changed, 133 insertions(+), 116 deletions(-) create mode 100644 docs/docs/contributing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ea8c783..2bea9263 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,120 +1,10 @@ # Contributing To ZMK -Thanks for taking an interest in contributing to ZMK! After reading through the documentation, if -you have any questions, please come join us on the -[ZMK Discord Server][discord-invite]. +Thanks for taking an interest in contributing to ZMK! -## Code of Conduct +Please read through the [documentation](http://www.zmkfirmware.dev/docs) first, +which includes information on +[contributing](http://www.zmkfirmware.dev/docs/contributing). -All community members are expected to abide by the [Code of Conduct][code-of-conduct]. -For any and all conduct inquiries or concerns, please contact conduct@zmkfirmware.dev. - -[code-of-conduct]: https://github.com/zmkfirmware/zmk/blob/main/CODE_OF_CONDUCT.md - -## How Can I Contribute - -There are many different ways that you can contribute to ZMK, several of which require no coding -abilities. These include: - -- Chat Support -- Issue Reporting/Commenting -- Testing -- Documentation -- Code Contributions - -## Chat Support - -Providing user support on the [ZMK Discord Server][discord-invite] is a great way to help the -project. In particular, answering questions in the [#help](https://discord.com/channels/719497620560543766/719909884769992755) channel is incredibly appreciated. - -## Issue Reporting/Commenting - -Often, you might encounter unexpected behavior when building, flashing, or running the ZMK -firmware. Submitting or commenting on issues on GitHub is a great way to contribute to the -ZMK project. - -### Before Submitting a Report - -- Review the [Frequently Asked Questions](https://zmkfirmware.dev/docs/faq). -- Check the [Troubleshooting Guide](https://zmkfirmware.dev/docs/troubleshooting) for answers. -- Search the [open issues](https://github.com/zmkfirmware/zmk/issues) for an existing report that - matches your problem. - -### Opening A Report - -To open a report: - -- Head to https://github.com/zmkfirmware/zmk/issues/new -- Provide an accurate summary of the issue in the title. -- Provide as much detail as you can about the issue including: - - What [board/shield](https://zmkfirmware.dev/docs/faq#what-is-a-board) you are using. - - A link to the user repository, if you used it to build your firmware. - - Exact steps to reproduce the problem. - - Any relevant screenshots or [logs](https://zmkfirmware.dev/docs/dev-guide-usb-logging) - -## Testing - -The `help wanted` label will be added to any [pull requests](https://github.com/zmkfirmware/zmk/pulls?q=is%3Aopen+is%3Apr+label%3A%22help+wanted%22) -or [issues](https://github.com/zmkfirmware/zmk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) -where user testing can assist the ZMK contributors to verify fixes, confirm -bugs, etc. - -When providing testing feedback, please provide: - -- Exact steps used to test -- Any hardware details relevant to testing -- Pass/fail summary for testing. -- Full details of any failures, including: - - Logs - - Screenshots - -## Documentation - -Quality documentation is a huge part of what makes a successful project. Contributions to add -documentation to areas not currently covered are greatly appreciated. - -### Contributing - -- The documentation site can be found in the main ZMK repo, in the - [docs/](https://github.com/zmkfirmware/zmk/tree/main/docs) subdirectory. -- The documentation is maintained using [Docusaurus V2](https://v2.docusaurus.io/docs/). -- To get started, from the `docs/` directory, run `npm ci` and then `npm start`. -- Enhancements should be submitted as pull requests to the `main` branch of ZMK. - -## Code Contributions - -### Development Setup - -To get your development environment setup going, start at the -[basic setup](https://zmkfirmware.dev/docs/dev-setup) docs, and make sure you can build and flash -your own locally built firmware. - -### Formatting - -ZMK uses `clang-format` to ensure consist formatting for our source code. Before submitting your -changes, make sure you've manually run `clang-format`, or have your IDE configured to auto-format -on save. - -### Commit Messages - -The ZMK project is working towards, but not yet enforcing, the use of -[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages. - -Further documentation and details will be provided here soon. - -### Pull Requests - -When opening a pull request with your changes, please: - -- Submit the PR to the `main` branch of the - [`zmkfirmware/zmk`](https://github.com/zmkfirmware/zmk) repository. -- Use a descriptive title that summarizes the change. -- In the description, include: - - References to any open issues fixed by the PR. - - Feature added by the PR - - Bugs fixed by the PR. - - Testing you've performed locally. - - Requested testing by reviewers or testers. - - Screenshots or logs that support understanding the change. - -[discord-invite]: https://zmkfirmware.dev/community/discord/invite +If you have any questions, please come join us on the +[ZMK Discord Server](http://zmkfirmware.dev/community/discord/invite). diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md new file mode 100644 index 00000000..5e7ba9bb --- /dev/null +++ b/docs/docs/contributing.md @@ -0,0 +1,126 @@ +--- +title: Contributing to ZMK +sidebar_title: Contributing to ZMK +--- + +## Code of Conduct + +All community members are expected to abide by the +[Code of Conduct](https://github.com/zmkfirmware/zmk/blob/main/CODE_OF_CONDUCT.md). + +For any and all conduct inquiries or concerns, please contact +conduct@zmkfirmware.dev. + +## How Can I Contribute + +There are many different ways that you can contribute to ZMK, several of which +require no coding abilities. These include: + +- Chat Support +- Issue Reporting/Commenting +- Testing +- Documentation +- Code Contributions + +## Chat Support + +Providing user support on the +[ZMK Discord Server](http://zmkfirmware.dev/community/discord/invite) is a great +way to help the project. In particular, answering questions in the +[#help](https://discord.com/channels/719497620560543766/719909884769992755) +channel is incredibly appreciated. + +## Issue Reporting/Commenting + +Often, you might encounter unexpected behavior when building, flashing, or +running the ZMK firmware. Submitting or commenting on issues on GitHub is a +great way to contribute to the ZMK project. + +### Before Submitting a Report + +- Review the [Frequently Asked Questions](faq). +- Check the [Troubleshooting Guide](troubleshooting) for answers. +- Search the [open issues](https://github.com/zmkfirmware/zmk/issues) for an + existing report that matches your problem. + +### Opening A Report + +To open a report: + +- Head to https://github.com/zmkfirmware/zmk/issues/new +- Provide an accurate summary of the issue in the title. +- Provide as much detail as you can about the issue including: + - What [board/shield](faq#what-is-a-board) you are using. + - A link to the user repository, if you used it to build your firmware. + - Exact steps to reproduce the problem. + - Any relevant screenshots or [logs](development/usb-logging). + +## Testing + +The `help wanted` label will be added to any +[pull requests](https://github.com/zmkfirmware/zmk/pulls?q=is%3Aopen+is%3Apr+label%3A%22help+wanted%22) +or +[issues](https://github.com/zmkfirmware/zmk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) +where user testing can assist the ZMK contributors to verify fixes, confirm +bugs, etc. + +When providing testing feedback, please provide: + +- Exact steps used to test. +- Any hardware details relevant to testing. +- Pass/fail summary for testing. +- Full details of any failures, including: + - Logs + - Screenshots + +## Documentation + +Quality documentation is a huge part of what makes a successful project. +Contributions to add documentation to areas not currently covered are greatly +appreciated. + +### Contributing + +- The documentation site can be found in the main ZMK repo, in the + [docs/](https://github.com/zmkfirmware/zmk/tree/main/docs) subdirectory. +- The documentation is maintained using + [Docusaurus V2](https://v2.docusaurus.io/docs/). +- To get started, from the `docs/` directory, run `npm ci` and then `npm start`. +- Enhancements should be submitted as pull requests to the `main` branch of ZMK. + +## Code Contributions + +### Development Setup + +To get your development environment setup going, start at the +[basic setup](development/setup) docs, and make sure you can build and flash +your own locally built firmware. + +### Formatting + +ZMK uses `clang-format` to ensure consist formatting for our source code. Before +submitting your changes, make sure you've manually run `clang-format`, or have +your IDE configured to auto-format on save. + +### Commit Messages + +The ZMK project is working towards, but not yet enforcing, the use of +[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for +commit messages. + +Further documentation and details will be provided here soon. + +### Pull Requests + +When opening a pull request with your changes, please: + +- Submit the PR to the `main` branch of the + [`zmkfirmware/zmk`](https://github.com/zmkfirmware/zmk) repository. +- Use a descriptive title that summarizes the change. +- In the description, include: + - References to any open issues fixed by the PR. + - Feature added by the PR. + - Bugs fixed by the PR. + - Testing you've performed locally. + - Requested testing by reviewers or testers. + - Screenshots or logs that support understanding the change. diff --git a/docs/sidebars.js b/docs/sidebars.js index 8fc1dc54..aafcf05f 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -7,6 +7,7 @@ module.exports = { "user-setup", "customization", "troubleshooting", + "contributing", ], Features: [ "features/keymaps",