From bd708f16bc477f98aad68ad203826605e0298b8a Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Thu, 9 May 2024 00:58:25 -0700 Subject: [PATCH] Documentation (#7166) I found it difficult to find the instructions for setting up a development environment with my usual GitHub habits. In fact, I assumed they don't exist and missed the very helpful information. I hope that this commit will help others find them. --- CONTRIBUTING.md | 3 ++- docs/contributing/making-a-pull-request.md | 14 +++++++++----- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3928cce0a..f24beffb0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,4 +58,5 @@ and brings value to both new and experienced users of Material for MkDocs. [Request a change]: docs/contributing/requesting-a-change.md [Ask a question]: https://github.com/squidfunk/mkdocs-material/discussions [Add a translation]: docs/contributing/adding-translations - [Create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls + [Create a pull request]: docs/contributing/making-a-pull-request.md + diff --git a/docs/contributing/making-a-pull-request.md b/docs/contributing/making-a-pull-request.md index 41b4f91f9..9a485c5e1 100644 --- a/docs/contributing/making-a-pull-request.md +++ b/docs/contributing/making-a-pull-request.md @@ -102,7 +102,11 @@ sequenceDiagram branch will be relatively short-lived and will disappear at the end, when your changes have been incorporated into the codebase. -4. Next comes the iterative process of making edits, committing them to your +4. If you intend to make any code changes, as opposed to working on + documentation only, you will need to [set up a development + environment](#setting-up-a-development-environment). + +5. Next comes the iterative process of making edits, committing them to your clone. Please commit in sensible chunks that constitute a piece of work instead of committing everything in one go. @@ -112,23 +116,23 @@ sequenceDiagram reviewer in mind when committing. In particular, make sure to write meaningful commit messages. -5. Push your work up to your fork regularly. +6. Push your work up to your fork regularly. -6. You should also keep an eye on changes in the Material for MkDocs repository +7. You should also keep an eye on changes in the Material for MkDocs repository you cloned. This is especially important if you work takes a while. Please try and merge any concurrent changes into your fork and into your branch regularly. You *must* do this at least once before creating a pull request, so make your life easier and do it more often so as to minimize the risk of conflicting changes. -7. Once you are happy that your changes are in a state that you can describe +8. Once you are happy that your changes are in a state that you can describe them in a *draft* pull request, you should create this. Make sure to reference any previous discussions or issues that gave rise to your work. Creating a draft is a good way to get *early* feedback on your work from the maintainer or others. You can explicitly request reviews at points where you think this would be important. -8. Review your work as if you were the reviewer and fix any issues with your +9. Review your work as if you were the reviewer and fix any issues with your work so far. Look critically at the diffs of the files that you have changed. In particular, pay attention to whether the changes are as small as possible and whether you have follow the general coding style used in the project.