Process of making new PasDoc release

1. Introduction

This page describes the process of making a new PasDoc release. Unless you’re a PasDoc maintainer, you probably don’t care about the details described here.

2. Change version number to next stable

  • Change version of all packages in source/packages/. Right now this means just changing source/packages/lazarus/pasdoc_package.lpk. (Delphi packages don’t store PasDoc version now.)

  • change VERSION in pasdoc/Makefile

  • change PASDOC_VERSION and PASDOC_DATE in source/components/PasDoc_Versions.pas

  • make && ./bin/pasdoc --version should show the new version number and date.

  • make dist-linux-x86_64 should create a tar.gz file with the new version number in its name.

Make last version number even to signify stable release, like 1.2.4.

3. Write ChangeLog entry

Make sure you have nice entry in https://github.com/pasdoc/pasdoc/blob/master/ChangeLog.md file in pasdoc sources.

We try to update this changelog file while developing PasDoc (each time someone does something significant, it’s immediately added to the changelog). So at this point, mainly review and finalize (write new verion number and release date) changelog entry.

4. Update docs

Remove from the documentation text

Note that this feature is not available in latest released pasdoc version, x.y.z. You must download and compile pasdoc yourself or use DevelopmentSnapshots to use this feature.

5. Update AutoDoc

  • It’s a good idea to upload PasDocAutoDoc at this time, like this:

    cd pasdoc/source/autodoc/
pasdoc --version # make sure latest version of pasdoc is used
make clean public upload

cd  ../../../pasdoc.github.io/
git commit -m "Updated autodoc"
git push

6. Prepare tag and GitHub release

7. Build and test all releases (automated now)

Note: This step is automated now, using GitHub Actions to automatically test and build PasDoc. Just switch release_tag in .github/workflows/build.yml to the new tag and push it, and GitHub Actions will do the rest.

Below we describe how to do things manually, just in case.

  • Make sure you have the latest stable FPC and Lazarus versions.

  • Run all the tests by

    make tests

    There are various comments inside tests/run_all_tests.sh about what is really happening. It runs various other tests we have prepared, it even compares the output with some "designated correct" output.

    To be sure, you should run these tests on all targets.

  • To build for the current platform (OS and architecture) call this:

    make clean build-fpc-release

    Note that it’s important to call clean before build-…​, otherwise you risk that some units were left as compiled with debug options.

    To build for indicated platform and package to zip/tar.gz (this will call clean build-fpc-release as first steps):

    make dist-<os/arch>

  • The make dist-…​ will automatically compile and include pasdoc_gui binary (using lazbuild to compile Lazarus package and project in batch mode). But you can also compile it manually:

    lazbuild source/packages/lazarus/pasdoc_package.lpk
lazbuild source/gui/pasdoc_gui.lpi

    For basic test of pasdoc_gui, open the project with pasdoc’s autodoc source/autodoc/autodoc.pds and hit "Generate".

8. Make release public

  • Make the release non-draft on GitHub.

  • Mark it as "latest", make sure latest release page links to it.

  • Update our website to link to latest release:

    • edit _config.yml

    • edit also src/_layouts/default.html if plaforms changed.

    • make

    • commit and push

    • once live, download all linked releases to make sure links are OK.

9. Announce new release everywhere

Really, really large and significant improvements may be signalled by changing the project’s description:

10. Prepare for next release

  • ChangeLog.md file should start with line

    ## Upcoming Next Release

    • Repeat the steps from "Change version number to next stable", but :

  • Switch back release_tag: snapshot in .github/workflows/build.yml.