Common instructions for my Python projects so I need to manage only one documentation. https://docs.franco.net.eu.org/fpydocs/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
fpydocs/docs/workflow_common.rst

9.0 KiB

Workflow [common]

Rules

  • Assume that the root of the repository is ./.
  • 3.5 <= Python version < 4
  • Variables are marked with braces and the dollar sign, e.g: ${variable}.

Variable reference

Variable name Description
project_name the name of the project
project_directory usually equal to project_name
projects_aur_git_directory the directory of the corresponding AUR package
gpg_signing_key a valid PGP key used to sign commits
dev_branch development git branch
version_id the version identifier used in the git tag
${MAJOR} a variable of the Semantic Versioning document
${MINOR} a variable of the Semantic Versioning document
${PATCH} a variable of the Semantic Versioning document

Sequence

Follow these instructions in sequential order.

1. preliminary configuration

  • IF not enabled previously setup git signing
  • git config commit.gpgsign true
  • git config user.signingkey ${gpg_signing_key}
  • IF not enabled previously setup a bare git repository serving static pages. Follow this blog post
  • IF AUR create an Arch Linux vm and setup a post-receive git hook in a bare repository. See this and use the provided "post-receive git hook for AUR packages" blueprint:
  • git init --bare ${project_name}
  • copy the blueprint into repo/hooks and set it as executable

  • add the pacman command to the ones not requiring password in the sudoers file, using visudo:

    :

    build-user ALL=NOPASSWD: /bin/pacman
  • on the local repository (development machine) create a new remote called packages-aur which points to the Arch Linux vm.

  • create a repository containing the AUR source. Add a normal origin remote and a git aur remote that to points to https://aur.archlinux.org/"$(basedir "${projects_aur_git_directory}")".git

2. finish working on the development branch

  • cd ${project_directory}
  • check that the current branch is not master
  • IF needed, create a new asciinema demo file and upload it
  • cd ./asciinema
  • IF there have significant been changes from the previous version
  • modify the ${project_name}_asciinema_${MAJOR}_${MINOR}_${PATCH}_demo.sh file accordingly
  • pipenv run asciinema rec --command=./${project_name}_asciinema_${MAJOR}_${MINOR}_${PATCH}_demo.sh ${project_name}_asciinema_${MAJOR}_${MINOR}_${PATCH}.json
  • pipenv run asciinema play ${project_name}_asciinema_${MAJOR}_${MINOR}_${PATCH}.json
  • pipenv run asciinema upload ${project_name}_asciinema_${MAJOR}_${MINOR}_${PATCH}.json
  • edit the ./README.rst file with the new asciinema link
  • ELSE
  • ln -s ${project_name}_asciinema_${MAJOR}_${OLD_MINOR}_${OLD_PATCH}_demo.sh ${project_name}_asciinema_${MAJOR}_${MINOR}_${PATCH}_demo.sh
  • ln -s ${project_name}_asciinema_${MAJOR}_${OLD_MINOR}_${OLD_PATCH}.json ${project_name}_asciinema_${MAJOR}_${MINOR}_${PATCH}.json
  • git add -A
  • git commit -m "An interesing message."
  • git push

3. update version numbers, requirements, etc...

  • FOREACH file update version numbers:
  • ./setup.py
  • ./docs/conf.py
  • all downstream distribution packages (see the ./packages directory)
  • IF there have been dependencies updates update ./Pipfile and ./setup.py. Read the changelogs of the dependencies and decide what packages to update.
  • make uninstall-dev; make install-dev
  • make doc
  • make test
  • make install
  • cd ~ && python3 -c "import ${package_name}" && cd ${OLDPWD}
  • make uninstall
  • make clean
  • FOREACH changed file update copyright years, emails and contributors:
  • ./README.rst
  • ./docs/conf.py
  • ./docs/copyright_license.rst
  • all Python source files
  • all downstream distribution packages (see the ./packages directory)
  • git add -A
  • git commit -m "Preparing for new release."
  • git push

4. update the documentation

  • make clean && make doc
  • rm -rf ~/html && cp -aR docs/_build/html ~
  • git branch --delete --force docs
  • git checkout --orphan docs
  • git rm --cached -r .
  • git clean -f && git clean -f -d
  • mv ~/html/{*,.nojekyll,.buildinfo} .
  • git add -A
  • git commit --no-verify -m "New release."
  • git push --force deploy-docs docs

5. merge the branches and tag the release

  • git checkout master
  • git merge ${dev_branch}
  • git tag -s -a ${version_id} -m "Some sensible comments highlighting relevant changes from the previous release."
  • git push
  • git push --tags

6. upload the package to PyPI

  • IF the package is present on PyPI:
  • make clean
  • make dist
  • make upload

7. upload the package on the software page

  • follow the instructions reported here

8. update downstream distribution packages

  • IF AUR:
    • git push --atomic packages-aur master ${MAJOR}.${MINOR}.${PATCH}
    • make clean
    • git branch -D packages-aur && git fetch --all && git checkout packages-aur
    • cp PKGBUILD .SRCINFO ${projects_aur_git_directory}
    • git checkout master
    • cd ~/${projects_aur_git_directory}
    • git add PKGBUILD .SRCINFO
    • git commit -m "New release."
    • git push && git push aur

9. other