From 09ff0ab247fa8d00d84ac7800dd17c82b11473b6 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Sun, 10 Dec 2023 14:00:09 +0100 Subject: [PATCH] Update CONTRIBUTING.md --- CONTRIBUTING.md | 137 +++++++++++++++++++++++------- mkdocs/themes/mkdocs/css/base.css | 2 +- 2 files changed, 105 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 840c3ba8..6bac5771 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ An introduction to contributing to the MkDocs project. -The MkDocs project welcomes, and depends, on contributions from developers and +The MkDocs project welcomes contributions from developers and users in the open source community. Contributions can be made in a number of ways, a few examples are: @@ -11,68 +11,126 @@ ways, a few examples are: - Bug reports and patch reviews For information about available communication channels please refer to the -[README](https://github.com/mkdocs/mkdocs/blob/master/README.md) file in our +[README](https://github.com/mkdocs/mkdocs#readme) file in our GitHub repository. -## Code of Conduct - -Everyone interacting in the MkDocs project's codebases, issue trackers, chat -rooms, and mailing lists is expected to follow the [PyPA Code of Conduct]. - ## Reporting an Issue Please include as much detail as you can. Let us know your platform and MkDocs -version. If the problem is visual (for example a theme or design issue) please -add a screenshot and if you get an error please include the full error and +version. If the problem is visual (for example a theme or design issue), please +add a screenshot. If you get an error, please include the full error message and traceback. -## Testing the Development Version +It is particularly helpful if an issue report touches on all of these aspects: + +1. What are you trying to achieve? + +2. What is your `mkdocs.yml` configuration (+ other relevant files)? Preferably reduced to the minimal reproducible example. + +3. What did you expect to happen when applying this setup? + +4. What happened instead and how didn't it match your expectation? + +## Trying out the Development Version If you want to just install and try out the latest development version of -MkDocs you can do so with the following command. This can be useful if you +MkDocs (in case it already contains a fix for your issue), +you can do so with the following command. This can be useful if you want to provide feedback for a new feature or want to confirm if a bug you have encountered is fixed in the git master. It is **strongly** recommended that you do this within a [virtualenv]. ```bash -pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz +pip install git+https://github.com/mkdocs/mkdocs.git ``` -## Installing for Development +## Installing MkDocs for Development -First you'll need to fork and clone the repository. Once you have a local -copy, run the following command. It is **strongly** recommended that you do -this within a [virtualenv]. +Note that for development you can just use [Hatch] directly as described below. If you wish to install a local clone of MkDocs anyway, you can run `pip install --editable .`. It is **strongly** recommended that you do this within a [virtualenv]. + +## Installing Hatch + +The main tool that is used for development is [Hatch]. It manages dependencies (in a virtualenv that is created on the fly) and is also the command runner. + +So first, [install it][install Hatch]. Ideally in an isolated way with **`pipx install hatch`** (after [installing `pipx`]), or just `pip install hatch` as a more well-known way. + +## Running all checks + +To run **all** checks that are required for MkDocs, just run the following command in the cloned MkDocs repository: ```bash -pip install --editable . +hatch run all ``` -This will install MkDocs in development mode which binds the `mkdocs` command -to the git repository. +**This will encompass all of the checks mentioned below.** -## Running the tests +All checks need to pass. -To run the tests, it is recommended that you use [Hatch]. +### Running tests -Install Hatch using [pip] by running the command `pip install hatch`. -Then the test suite can be run for MkDocs by running the command `hatch run all` in the -root of your MkDocs repository. +To run the test suite for MkDocs, run the following commands: + +```bash +hatch run test:test +hatch run integration:test +``` It will attempt to run the tests against all of the Python versions we support. So don't be concerned if you are missing some. The rest will be verified by [GitHub Actions] when you submit a pull request. -## Formatting the code +### Python code style -Python code within MkDocs' code base is formatted using [Black] and [Isort]. -You can automatically format the code according to these tools -with `hatch run style:format`. +Python code within MkDocs' code base is formatted using [Black] and [Isort] and lint-checked using [Ruff], all of which are configured in `pyproject.toml`. + +You can automatically check and format the code according to these tools with the following command: + +```bash +hatch run style:fix +``` + +The code is also type-checked using [mypy] - also configured in `pyproject.toml`, it can be run like this: + +```bash +hatch run types:check +``` + +### Other style checks + +There are several other checks, such as spelling and CSS style. To run all of them, use this command: + +```bash +hatch run lint:check +``` + +### Documentation of MkDocs itself + +After making edits to files under the `docs/` dir, you can preview the site locally using the following command: + +```bash +hatch run docs:serve +``` + +Note that any 'WARNING' should be resolved before submitting a contribution. + +Documentation files are also checked by markdownlint, so you should run this as well: + +```bash +hatch run lint:check +``` + +If you add a new plugin to mkdocs.yml, you don't need to add it to any "requirements" file, because that is managed automatically. + +> INFO: If you don't want to use Hatch, for documentation you can install requirements into a virtualenv, in one of these ways (with `.venv` being the virtualenv directory): +> +> ```bash +> .venv/bin/pip install -r requirements/requirements-docs.txt # Exact versions of dependencies. +> .venv/bin/pip install -r $(mkdocs get-deps) # Latest versions of all dependencies. +> ``` ## Translating themes -To localize a theme to your favorite language, follow the guide on [Translating -Themes]. We welcome translation Pull Requests! +To localize a theme to your favorite language, follow the guide on [Translating Themes]. We welcome translation pull requests! ## Submitting Pull Requests @@ -83,6 +141,11 @@ Once you think the code is ready to be reviewed, push it to your fork and send a pull request. For a change to be accepted it will most likely need to have tests and documentation if it is a new feature. +When working with a pull request branch: +Unless otherwise agreed, prefer `commit` over `amend`, and `merge` over `rebase`. Avoid force-pushes, otherwise review history is much harder to navigate. For the end result, the "unclean" history is fine because most pull requests are squash-merged on GitHub. + +Do *not* add to *release-notes.md*, this will be written later. + ### Submitting changes to the builtin themes When installed with `i18n` support (`pip install 'mkdocs[i18n]'`), MkDocs allows @@ -110,12 +173,20 @@ Contributors are not expected to provide translations with their changes to a theme's templates. However, they are expected to include an updated `pot` file so that everything is ready for translators to do their job. +## Code of Conduct + +Everyone interacting in the MkDocs project's codebases, issue trackers, chat +rooms, and mailing lists is expected to follow the [PyPA Code of Conduct]. + [virtualenv]: https://virtualenv.pypa.io/en/latest/user_guide.html -[pip]: https://pip.pypa.io/en/stable/ [Hatch]: https://hatch.pypa.io/ +[install Hatch]: https://hatch.pypa.io/latest/install/#pip +[installing `pipx`]: https://pypa.github.io/pipx/installation/ [GitHub Actions]: https://docs.github.com/actions [PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/ [Translating Themes]: https://www.mkdocs.org/dev-guide/translations/ [Jinja's i18n extension]: https://jinja.palletsprojects.com/en/latest/extensions/#i18n-extension -[Black]: https://pypi.org/project/black/ -[Isort]: https://pypi.org/project/isort/ +[Ruff]: https://docs.astral.sh/ruff/ +[Black]: https://black.readthedocs.io/ +[Isort]: https://pycqa.github.io/isort/ +[mypy]: https://mypy-lang.org/ diff --git a/mkdocs/themes/mkdocs/css/base.css b/mkdocs/themes/mkdocs/css/base.css index 26103413..a396ae53 100644 --- a/mkdocs/themes/mkdocs/css/base.css +++ b/mkdocs/themes/mkdocs/css/base.css @@ -226,7 +226,7 @@ blockquote { text-align: left; } -.admonition.note, details.note { /* csslint allow: adjoining-classes */ +.admonition.note, details.note, .admonition.info, details.info { /* csslint allow: adjoining-classes */ color: #2e6b89; background-color: #e2f0f7; border-color: #bce8f1;