From 832f14ce9a4d00c2dfb88e8cb02e2defadb76ba9 Mon Sep 17 00:00:00 2001 From: Jonathan Hartley Date: Wed, 19 Oct 2022 13:25:39 -0500 Subject: [PATCH] README tweaks --- README-hacking.md | 37 +++++++++++++++++++++---------------- README.rst | 25 +++++++++++-------------- 2 files changed, 32 insertions(+), 30 deletions(-) diff --git a/README-hacking.md b/README-hacking.md index ad212a2a..ff65f017 100644 --- a/README-hacking.md +++ b/README-hacking.md @@ -66,12 +66,14 @@ target. ## Release checklist -1. Check the CHANGELOG is updated with everything since the last release. - Update CHANGELOG.rst with the new release version (move the comment for - "Current release") +1. Check the CHANGELOG.rst is updated with everything since the last release, + including links to merged PRs. Move the "Current release" comment from the + previous version number. 2. First we'll make a candidate release. Ensure the '.rc1' suffix is - present on `__version__` in `colorama/__init.py__.py`. + present on `__version__` in `colorama/__init.py__.py`, eg: + + __version__ = '0.4.6rc1' 3. Run the tests locally on your preferred OS, just to save you from doing the subsequent time-consuming steps while there are still obvious problems @@ -86,22 +88,25 @@ target. * `make bootstrap` * `make test` -4. Tag the current commit with the `__version__` from `colorama/__init__.py`. +4. Verify you're all committed, merged to master. + +5. Tag the current commit with the `__version__` from `colorama/__init__.py`. We should start using [annotated tags for releases](https://www.tartley.com/posts/til-git-annotated-tags/), so: git tag -a -m "" $version git push --follow-tags -5. Verify you're all committed, merged to master, and pushed to origin (This - triggers a CI build, which we'll check later on) +6. Push to origin (This triggers a CI build, which we'll check later on) + + git push origin master -6. Build the distributables (sdist and wheel), on either OS: +7. Build the distributables (sdist and wheel), on either OS: * Windows: `.\build.ps1` * Linux: `make build` -7. Test the distributables on both OS. Whichever one you do 2nd will get an +8. Test the distributables on both OS. Whichever one you do 2nd will get an HTTP 400 response on uploading to test.pypi.org, but outputs a message saying this is expected and carries on: @@ -111,27 +116,27 @@ target. (This currently only tests the wheel, but [should soon test the sdist too](https://github.com/tartley/colorama/issues/286).) -8. Check the [CI builds](https://github.com/tartley/colorama/actions/) +9. Check the [CI builds](https://github.com/tartley/colorama/actions/) are complete and all passing. -9. Upload the distributables to PyPI: +10. Upload the distributables to PyPI: * On Windows: `.\release.ps1` * On Linux: `make release` -10. Test by installing the candidate version from PyPI, and sanity check it with +11. Test by installing the candidate version from PyPI, and sanity check it with 'demo.sh', making sure this is running against the PyPI installation, not local source. -11. Maybe wait a day for anyone using pre-release installs to report any +12. Maybe wait a day for anyone using pre-release installs to report any problems? -12. Remove the '.rcX' suffix from `__version__` in +13. Remove the '.rcX' suffix from `__version__` in `colorama/__init__.py`. -13. Repeat steps 5 to 10, for the actual (non-candidate) release. +14. Repeat steps 5 to 10, for the actual (non-candidate) release. -14. Bump the version number in `colorama/__init__.py`, and add a 'dev1' +15. Bump the version number in `colorama/__init__.py`, and add a 'dev1' suffix, eg: `0.4.5dev1` diff --git a/README.rst b/README.rst index 7b173d83..0b6e52a4 100644 --- a/README.rst +++ b/README.rst @@ -26,7 +26,6 @@ cursor positioning) work under MS Windows. If you find Colorama useful, please |donate| to the authors. Thank you! - Installation ------------ @@ -40,7 +39,6 @@ No requirements other than the standard library. # or conda install -c anaconda colorama - Description ----------- @@ -146,7 +144,6 @@ Most users should depend on ``colorama >= 0.4.6``, and use indefinitely for backwards compatibility, but we don't plan to fix any issues with it, also for backwards compatibility. - Colored Output .............. @@ -180,6 +177,10 @@ then consider using one of the above highly capable libraries to generate colors, etc, and use Colorama just for its primary purpose: to convert those ANSI sequences to also work on Windows: +SIMILARLY, do not send PRs adding the generation of new ANSI types to Colorama. +We are only interested in converting ANSI codes to win32 API calls, not +shortcuts like the above to generate ANSI characters. + .. code-block:: python from colorama import just_fix_windows_console @@ -205,14 +206,12 @@ These are fairly well supported, but not part of the standard:: Fore: LIGHTBLACK_EX, LIGHTRED_EX, LIGHTGREEN_EX, LIGHTYELLOW_EX, LIGHTBLUE_EX, LIGHTMAGENTA_EX, LIGHTCYAN_EX, LIGHTWHITE_EX Back: LIGHTBLACK_EX, LIGHTRED_EX, LIGHTGREEN_EX, LIGHTYELLOW_EX, LIGHTBLUE_EX, LIGHTMAGENTA_EX, LIGHTCYAN_EX, LIGHTWHITE_EX - Cursor Positioning .................. ANSI codes to reposition the cursor are supported. See ``demos/demo06.py`` for an example of how to generate them. - Init Keyword Args ................. @@ -264,7 +263,6 @@ init(wrap=True): # Python 3 print(Fore.BLUE + 'blue text on stderr', file=stream) - Recognised ANSI Sequences ......................... @@ -333,15 +331,17 @@ initial characters, are not recognised or stripped. It would be cool to add them though. Let me know if it would be useful for you, via the Issues on GitHub. - Status & Known Problems ----------------------- I've personally only tested it on Windows XP (CMD, Console2), Ubuntu (gnome-terminal, xterm), and OS X. -Some presumably valid ANSI sequences aren't recognised (see details below), -but to my knowledge nobody has yet complained about this. Puzzling. +Some valid ANSI sequences aren't recognised. + +If you're hacking on the code, see `README-hacking.md`_. ESPECIALLY, see the +explanation there of why we do not want PRs that allow Colorama to generate new +types of ANSI codes. See outstanding issues and wish-list: https://github.com/tartley/colorama/issues @@ -351,18 +351,14 @@ I'd love to hear about it on that issues list, would be delighted by patches, and would be happy to grant commit access to anyone who submits a working patch or two. -If you're hacking on the code, see `README-hacking.md`_. - .. _README-hacking.md: README-hacking.md - License ------- Copyright Jonathan Hartley & Arnon Yaari, 2013-2020. BSD 3-Clause license; see LICENSE file. - Professional support -------------------- @@ -383,10 +379,11 @@ Professional support .. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-colorama?utm_source=pypi-colorama&utm_medium=referral&utm_campaign=readme - Thanks ------ +See the CHANGELOG for more thanks! + * Marc Schlaich (schlamar) for a ``setup.py`` fix for Python2.5. * Marc Abramowitz, reported & fixed a crash on exit with closed ``stdout``, providing a solution to issue #7's setuptools/distutils debate,