Generate this doc as html so the links works by issuing:
rst2html.py --traceback release_checklist_details.txt > release_checklist_details.html
in a venv with doctutils installed.
While doing this keep notes about discoveries in python and libs versions required, they will be handy to update documentation.
At least the combinations of (py_min, py_max) x (pyglet_min, pyglet_max), with special attention to (py_max, pyglet_max) should be tested.
Use cocos-testcmp to run the unittests and compare snapshots with a know good reference.
For each python version supported, or at least py_min, py_max, do
Scripts outside test/ should be tested, meaning manual run and eyeballing they look good Fix any discovered issue. Code fixes that touch cocos/ must uncheck the 'Test, part one', and all Test, part two
update pip before starting build
built source package with:
python setup.py sdist >../sdist.log and
This will leave the built source package under dist/, typically a cocos2d-0.X.Y.tar.gz or cocos2d-0.X.Y.zip
pip installation works as expected installing from the source package
Create a new py_env, activate
Update pip
pip install from pkg:
pip install cocos2d-0.X.Y.tar.gz
No errors should have been reported by pip
The dependencies pulled from pypi come at the expected versions
Check all the files under cocos/ are present at the directory pip installed the package, use Meld or other directory compare tool. To know where pip installed the package issue a 'python -c "import cocos;print(cocos.__file__)"'
smoketest installed cocos is functional: install numpy and pillow, then do a quick run to the following scripts, they should run ok
Tag the release in the repo:
git tag -a release-X.Y.Z -m "tagging release-X.Y.Z" git push --follow-tags
If needed, update release_checklist.txt and release_checklist_details.txt , then regenerate release_checklist_details.html and commit & push the changes
Congratulate yourself and relax :-)
(Write here things discovered that may need further actions)
Details may vary by OS and shell, you can lookup details in the Python's docs for module venv.
create:
>py -3.7 -m venv venv_directory
Creates a venv_directory and sets there the files needed
activate:
>venv_directory\Scripts\activate
When the venv is active, the command 'python' will invoke the python in venv
deactivate:
>deactivate
create:
$ python -m venv venv_directory
Creates a venv_directory and sets there the files needed
activate:
$ source venv_directory/Scripts/activate
When the venv is active, the command 'python' will invoke the python in venv
deactivate:
$ deactivate
venvdir/Scripts/python will run the python in the venv, meaning imports will give modules and packages installed in that venv, even if the environmet is not activated
First of all upgrade pip to last version:
python -m pip install pip --upgrade
Installing from pypi
Some packages have a pypi name different from the import name, by example pypi name 'pillow' uses 'PIL' to import, or pypi name 'cocos2d' uses import name 'cocos'. The pip command needs the pypi name.
The pypi name can be given version restrictions, and at least in windows when the version restriction includes a '>' or a '<' you must use quotes so the shell don't take as a redirect. Quoting is done with double quotes in windows, single in linux.
Examples, you must use the quote character appropriate to your shell:
python -m pip install pillow python -m pip install 'pillow<8' python -m pip install "pyglet==1.4.11" python -m pip install 'pyglet<2,>1.4.10'
Installing from a local package archive
A package built with sdist build ... will produce a file <pkg_name>.[zip | tar.gz | whl]
To install from that file, use:
python -m pip install filename
Installing in developer mode
If dir_z has a setup.py file, then running the command:
python -m pip install -e dir_z
will install the package and dependencies described on the setup.py
This is a common style to install from a DVCS (git, etc) clone
This app lives at https://github.com/los-cocos/cocos-testcmp
Instructions to run in cocos-testcmp's Readme
Last build (2023) installed markupsafe==2.0.1, jinja2==2.11.2, sphinx==3.2.0 (in that order)
set the SPHINXDIR environment to the (venv dir)/Scripts
cd docgen
to clean, make clean in Windows, makefile clean in linux
to build, make html in Windows, makefile html in linux
the build will create a log with warnings and errors, docgen/warnings.log
some warnings are expected, in windows without sdl installed the build ends with 24 warnings:
WARNING: while setting up extension sphinx.addnodes: node class 'meta' is already registered, its visitors will be overridden WARNING: html_static_path entry '_static' does not exist WARNING: missing attribute mentioned in :members: or __all__: module cocos.audio, attribute SDL WARNING: missing attribute mentioned in :members: or __all__: module cocos.audio, attribute pygame WARNING: autodoc: failed to import module 'SDL' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.array' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.audio' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.constants' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.darwin' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.dll' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.endian' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.error' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.mixer' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.rwops' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.sound' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.timer' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'SDL.version' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'pygame' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'pygame.base' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'pygame.mixer' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'pygame.music' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found WARNING: autodoc: failed to import module 'pygame.version' from module 'cocos.audio'; the following exception was raised: Dynamic library "SDL" was not found D:\dev\cocos2020\docgen\api\modules.txt: WARNING: document isn't included in any toctree D:\dev\cocos2020\docgen\euclid.txt: WARNING: document isn't included in any toctree
To start navigating the docs, open docgen_buildhtmlindex.html in a browser
In the venv where Sphix was installed do a:
rst2html.py --traceback file >out.html
Fix any traceback appearing, open the .html in a browser, even if they are no warnings, and see if the view is the desired one.
In the activated venv used ro build the package, at the root of Working Directory used ro build the package:
pip install twine twine upload -u user -p pwd dist/*
Obviously use your pypi user and pwd