From 82e0af8a9ec5fc3c69826aee9a17c2da8db57763 Mon Sep 17 00:00:00 2001 From: benoit Date: Wed, 30 Aug 2023 10:06:53 +0200 Subject: [PATCH] Update README CONTRIBUTING RELEASE * README: add information pertaining to shell completion; * CONTRIBUTING: remove release information; * RELEASE: create a dedicated file with all the relevant release information. --- CONTRIBUTING.md | 16 +--------------- README.md | 27 ++++++++++++++++++++++++--- RELEASE.md | 38 ++++++++++++++++++++++++++++++++++++++ docs/make_readme.sh | 27 ++++++++++++++++++++++++--- 4 files changed, 87 insertions(+), 21 deletions(-) create mode 100644 RELEASE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 28b9a33..bc3ca89 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,7 +43,7 @@ A vagrant file can be found in [this repository](https://github.com/ioguix/vagrant-patroni) to generate a patroni/etcd setup. -The `README.md` can be geneated with `./docs/make_readme.sh`. +The `README.md` can be generated with `./docs/make_readme.sh`. ## Executing Tests @@ -99,17 +99,3 @@ Here's an example usage: ```bash ./vagrant/check_patroni.sh http://10.20.30.51:8008 ``` - -## Release - -Update the Changelog. - -The package is generated and uploaded to pypi when a `v*` tag is created (see -`.github/workflow/publish.yml`). - -Alternatively, the release can be done manually with: - -``` -tox -e build -tox -e upload -``` diff --git a/README.md b/README.md index af726eb..7cfe808 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ $ pip install git+https://github.com/dalibo/check_patroni.git check_patroni works on python 3.6, we keep it that way because patroni also supports it and there are still lots of RH 7 variants around. That being said -python 3.6 has been EOL for age and there is no support for it in the github +python 3.6 has been EOL for ages and there is no support for it in the github CI. ## Support @@ -98,8 +98,8 @@ A match is found when: `start <= VALUE <= end`. For example, the following command will raise: -* a warning if there is less than 1 nodes, wich can be translated to outside of range [2;+INF[ -* a critical if there are no nodes, wich can be translated to outside of range [1;+INF[ +* a warning if there is less than 1 nodes, which can be translated to outside of range [2;+INF[ +* a critical if there are no nodes, which can be translated to outside of range [1;+INF[ ``` check_patroni -e https://10.20.199.3:8008 cluster_has_replica --warning 2: --critical 1: @@ -115,6 +115,27 @@ Several options are available: * `--cert_file`: your certificate or the concatenation of your certificate and private key * `--key_file`: your private key (optional) +## Shell completion + +We use the [click] library which supports shell completion natively. + +Shell completion can be added by typing the following command or adding it to +a file spécific to your shell of choice. + +* for Bash (add to `~/.bashrc`): + ``` + eval "$(_CHECK_PATRONI_COMPLETE=bash_source check_patroni)" + ``` +* for Zsh (add to `~/.zshrc`): + ``` + eval "$(_CHECK_PATRONI_COMPLETE=zsh_source check_patroni)" + ``` +* for Fish (add to `~/.config/fish/completions/check_patroni.fish`): + ``` + eval "$(_CHECK_PATRONI_COMPLETE=fish_source check_patroni)" + ``` + +[click]: https://click.palletsprojects.com/en/8.0.x/shell-completion/?highlight=completion ## Cluster services diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..822e65d --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,38 @@ +# Release HOW TO + +## Preparatory changes + +* Review the **Unreleased** section, if any, in `CHANGELOG.md` possibly adding + any missing item from closed issues, merged pull requests, or directly the + git history[^git-changes], +* Rename the **Unreleased** section according to the version to be released, + with a date, +* Bump the version in `check_patroni/__init__.py`, +* Rebuild the `README.md` (`cd docs; ./make_readme.sh`), +* Commit these changes (either on a dedicated branch, before submitting a pull + request or directly on the `master` branch) with the commit message `release + X.Y.Z`. +* Then, when changes landed in the `master` branch, create an annotated (and + possibly signed) tag, as `git tag -a [-s] -m 'release X.Y.Z' vX.Y.Z`, + and, +* Push with `--follow-tags`. + +[^git-changes]: Use `git log $(git describe --tags --abbrev=0).. --format=%s + --reverse` to get commits from the previous tag. + +## PyPI package + +The package is generated and uploaded to pypi when a `v*` tag is created (see +`.github/workflow/publish.yml`). + +Alternatively, the release can be done manually with: + +``` +tox -e build +tox -e upload +``` + +## GitHub release + +Draft a new release from the release page, choosing the tag just pushed and +copy the relevant change log section as a description. diff --git a/docs/make_readme.sh b/docs/make_readme.sh index 8c5dad9..824ac4b 100755 --- a/docs/make_readme.sh +++ b/docs/make_readme.sh @@ -42,7 +42,7 @@ $ pip install git+https://github.com/dalibo/check_patroni.git check_patroni works on python 3.6, we keep it that way because patroni also supports it and there are still lots of RH 7 variants around. That being said -python 3.6 has been EOL for age and there is no support for it in the github +python 3.6 has been EOL for ages and there is no support for it in the github CI. ## Support @@ -80,8 +80,8 @@ A match is found when: `start <= VALUE <= end`. For example, the following command will raise: -* a warning if there is less than 1 nodes, wich can be translated to outside of range [2;+INF[ -* a critical if there are no nodes, wich can be translated to outside of range [1;+INF[ +* a warning if there is less than 1 nodes, which can be translated to outside of range [2;+INF[ +* a critical if there are no nodes, which can be translated to outside of range [1;+INF[ ``` check_patroni -e https://10.20.199.3:8008 cluster_has_replica --warning 2: --critical 1: @@ -97,6 +97,27 @@ Several options are available: * `--cert_file`: your certificate or the concatenation of your certificate and private key * `--key_file`: your private key (optional) +## Shell completion + +We use the [click] library which supports shell completion natively. + +Shell completion can be added by typing the following command or adding it to +a file spécific to your shell of choice. + +* for Bash (add to `~/.bashrc`): + ``` + eval "$(_CHECK_PATRONI_COMPLETE=bash_source check_patroni)" + ``` +* for Zsh (add to `~/.zshrc`): + ``` + eval "$(_CHECK_PATRONI_COMPLETE=zsh_source check_patroni)" + ``` +* for Fish (add to `~/.config/fish/completions/check_patroni.fish`): + ``` + eval "$(_CHECK_PATRONI_COMPLETE=fish_source check_patroni)" + ``` + +[click]: https://click.palletsprojects.com/en/8.0.x/shell-completion/?highlight=completion _EOF_ readme readme "## Cluster services"