Skip to content

Instantly share code, notes, and snippets.

@switowski

switowski/Release checklist.md

Created October 20, 2017 09:38
Show Gist options
  • Save switowski/af7a5b1319fa9fbfd186af39d32b4930 to your computer and use it in GitHub Desktop.
Save switowski/af7a5b1319fa9fbfd186af39d32b4930 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
Release checklist.md

Prerequisites:

Checkout Invenio cookiecutter template:

$ git clone https://github.com/inveniosoftware/cookiecutter-invenio-module.git

1. Analyse module

  • Is I18N required? (In the later steps you will be checking if all strings are correctly extracted for I18n, so here just check if we need I18n for this module - usually it's true if there are some strings that will be exposed to the final user - like in the templates). NOTE: Currently we are skipping this step - we will work on proper I18n for all modules laster, so you can skip this step.
  • Is example application required? If the module is easy to test (for example by using just the API functions), then it doesn't need the example app (remember that each example app has to be kept up to date, which is a hassle if we want to do this for all the modules!). However, if the module is more complicated to start using it (for example, invenio-search requires you to setup ES and put some data there first), then we should have an example app. If the example app is required, then in the later steps you will be testing if it works correctly.
  • Is module using an extension class? Not all modules require extension class (usually, it's the base modules that will have the extension class).
  • Determine Cookiecutter variables (you will need those in the later steps):
    • Project name: Invenio-FunGenerator
    • Project shortname: invenio-fungenerator
    • Package name: invenio_fungenerator
    • GitHub repository: inveniosoftware/invenio-fungenerator
    • Description: (oneliner - get from e.g. README.rst)
    • Author name: CERN
    • Author email: info@inveniosoftware.org
    • Year: (get earliest year from header of e.g. setup.py)
    • Copyright holder: CERN
    • Copyright by intergovernmental: True
    • Superproject: Invenio
    • Transifex project: invenio-fungenerator
    • Extension class: (get from ext.py)
    • Configuration prefix: (get from config.py or ext.py)

1.1 Proof read API

  • Check open GitHub Issues about module - if you are in the middle of a sprint related to this module, check if there is something added to the sprint (usually, all the issues should be already checked at the beginning of the sprint, but maybe there is something new that pop up during the sprint).
  • Read and understand API - check if everything is clear, if method names are self-explanatory (or maybe they could be renamed to be more clear?).
  • Check existing API methods for feature completeness and correctness.
  • Check if new API methods is needed - it might be hard to come up with ideas for new API methods when checking the existing code, but sometimes when reading the code you might think "why the code doesn't have a method FOO to do this?".
  • Report anything that needs to be fixed on the GitHub repository.

2. Generate project structure using latest cookiecutter template

First we generate a new project skeleton structure using the latest cookiecutter template. We will later compare this skeleton with the current project structure to detect which files need changes.

First install click and cookiecutter if you don't already have them:

$ mkvirtualenv repocheck
$ pip install click cookiecutter

Next, generate the skeleton project structure (note that you will need to have the cookiecutter variables which was used initially ready - see previous section):

$ cookiecutter pathto/cookiecutter-invenio-module

3. Synchronize current project structure with new skeleton structure

Run the repocheck.py script in the cookiecutter-invenio-module:

$ python cookiecutter-invenio-module/scripts/repocheck.py \
  pathto/current/invenio-fungenerator pathto/skeleton/invenio-fungenerator

3.1 Check and fix diffs:

Note: The diffs only help to identify which parts might not be in sync with the latest project structure. Changes cannot be applied blindly and should be carefully reviewed if needed or not.

  • .editorconfig
  • .tx/config (not needed if module does not require I18N - i.e. entire .tx directory can be removed)
  • AUTHORS.rst - it will be different in those 2 files, but don't worry, leave it as it is and we will automatize it later.
  • CHANGES.rst - this file won't be equal!
  • docs/conf.py
  • INSTALL.rst
  • {{package_name}}/version.py
  • MANIFEST.in
    • Should be sorted and without comments from auto-updates
    • Should NOT contain include *.py
  • README.rst - check if there is no "this is experimental preview" note

3.2 Check and fix almost identical files (those files might not be equal, but there might be a good reason why they are not equal):

  • .dockerignore
  • .gitignore
  • babel.ini (not needed if module does not require I18N)
  • CONTRIBUTING.rst
  • docs/authors.rst
  • docs/changes.rst
  • docs/configuration.rst (may need changes if module is e.g. split in many extensions)
  • docs/contributing.rst
  • docs/index.rst
  • docs/installation.rst
  • docs/license.rst
  • docs/make.bat
  • docs/Makefile
  • docs/requirements.txt (may need changes in order for Sphinx documentation to build correctly on Read The Docs).
  • docs/usage.rst
  • LICENSE
  • pytest.ini
  • run-tests.sh
  • setup.cfg (note following sections should be removed if no I18N is needed compile_catalog, extract_messages, init_catalog, update_catalog)

3.3 Check following files manually (by comparing and diff'ing with template):

  • setup.py (repocheck.py will check some of the attributes)
    • same over all structure for file is used
    • package dependencies are sorted in alphabetical order
    • tests_require: review packages and their version numbers needed for tests
    • extras_require.
    • setup_requires - Remove Babel if no I18N is needed.
    • install_requires - Remove Flask-Babel if no I18N is needed.
    • setup() attributes. Check keywords
    • entry_points: Sorted and makes sense?
    • classifiers: Ensure Python version classifiers match with tested versions in .travis.yml as well as 'Development Status :: 4 - Beta',
  • .travis.yml
  • tests/conftest.py
    • Check instance_path and app fixtures. Should be using @pytest.fixture and app fixture should create application context.
    • Replace all occurrences of yield_fixture with fixture (yield_fixture is deprecated).
  • examples/app-fixtures.sh
    • Remove if no example app is needed.
    • Top of file should be identical. Remaining part should create any fixtures needed by the example application.
  • examples/app-setup.sh
    • Remove if no example app is needed.
    • Top of file should be identical. Remaining part should setup the base application, e.g. create instance directory.
  • examples/app-teardown.sh
    • Remove if no example app is needed.
    • Top of file should be identical. Remaining part should clean up any files created by the app and setup and fixtures scripts.
  • examples/app.py
    • Remove if no example app is needed.
  • tests/test_examples_app.py
    • Remove if no example app is needed.
    • example_app fixture should be identical.
    • Replace all occurrences of yield_fixture with fixture (yield_fixture is deprecated).
  • requirements-devel.txt
    • Important package dependencies should be listed here.
    • List of modules in.editorconfig:known_third_party should match 1-to-1 all devel requirements.
  • config.py
    • Check if all variables are used and documented
    • Check if any config variables are set up in extension, refactor to config.py if possible.

3.4 Delete files no longer needed:

  • RELEASE-NOTES.rst

4. Code improvements:

  • General code improvements
    • Check code quality all over the module
    • Is the test coverage % sufficient across the whole module? (it should be at least 95%)
    • Is all core code (API, models) covered with unit test?
    • grep the module for "TODO"/"FIXME". Remove where no longer relevant.
  • Dependencies:
    • Remove unused dependencies in setup.py and requirements-devel.txt FlaskCLI extension.
    • Change double bracket "string" to 'string' if you spot it anywhere.

5. Example app:

  • Example app should be documented in docstring.
  • Example app should run according to documentation.
  • Example app documentation should be visible in ReadTheDocs (compare how it looks like in the modules that have already been released).

6. I18N - this step can be skipped for now.

  • Are all strings decorated as translation strings?
  • Have all strings be tested for correct translation - e.g. lazy vs. immediate?
  • Does Transifex project exists (or is it removed if I18N is not needed).
  • Have message catalogue been uploaded to Transifex.

7. Documentation:

7.1 Write

  • General documentation:
    • Update feature description in README.rst
    • Document usage / getting started guide inside package docstring (see example).
    • Make config variables self-documented and imported in the package docs under 'Configuration' section (see example and example). Note: there's exceptions to this pattern for some modules.
    • Are all API methods, classes and modules plugged in the documentation as autodoc?
    • Add intersphinx mappings where convenient and make sure they work in compiled documentation (see reference and config).
    • Are chapter/section underline (i.e. ==== or -----) matching the length of the section/chapter title?
  • Functional documentation
    • Document all public methods (docstrings with description and types).
    • Methods and functions that accept **kwargs should document potential arguments and mention if they are passed to another function/method which provides documentation for them.
    • Document signals.

7.2 Review (read the compiled documentation A-Z)

  • Is all imported autodoc documentation being loaded correctly?
  • Do all pages and sections contain some text?
  • Are all links on the page (API class references, intersphinx links) resolvable?
  • Are all text and characters rendered correctly?
    • Non-breaking newlines going outside the page?
    • Strange characters, half-escaped style markers inside docstrings (*, **, )
  • Docs are compiled and assembled from multiple file/package docstings into single pages - is the assembled block of text easy to read? Unify the compiled text if possible.
  • Create a new virtual environment and follow the installation and then getting started guide - does it actually work as described? Add and improve documentation if the description is missing something.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment