Package: releaseherald
Introductionreleaseheraldis a utility that can generate release notes. The only help it needs from
developers is to collect meaningful news fragments in a directory, and apply consistent tags.We believe releasenotes are an important aspect of a project, they should be convenient to read and easy to work with.
Ideally every pull request should come with an update of the releasenotes, if this
is a single file then one always run into merge conflicts, but if each PR has its own news fragment then this is easily
avoidable.releaseheraldis designed to be easy to extend, and there are just three guiding principals:version control in gitthe release notes for a version is fabricated from the news fragments created/modified between the two releasethe release number can be worked out from git tagsReleaseherald was inspired bytowncrier's philosophy.ConceptThe below diagram explains the concept and shows off the various data that flows intoreleaseherald.%% Unfortunately PyPi does not render this diagram so just please scroll it through

flowchart LR
    subgraph G[Git Repo]
        subgraph L1[Change since TAG 0.9.1]
            direction LR

            L1C3[Commit 3 TAG: 1.0.0]
            L1C2[Commit 2]
            L1C1[Commit 1]

            C3N2[news4.srt]
            C3N1[news3.srt]
            C2N1[news2.srt]
            C1N1[news1.srt]

            L1C3 --- C3N2
            L1C3 --- C3N1
            L1C2 --- C2N1
            L1C1 --- C1N1


        end

        subgraph L2 [Change since TAG 0.7.0]
            direction LR
            L2C3[Commit 3 TAG: 0.9.1]
            L2C2[Commit 2]
            L2C1[Commit 1]

            L2C3N1[news3.srt]
            L2C2N1[news2.srt]
            L2C1N1[news1.srt]

            L2C3 --- L2C3N1
            L2C2 --- L2C2N1
            L2C1 --- L2C1N1
        end
        subgraph L3 [Earlier changes]
            direction LR
            L3C2[Commit N TAG: 0.7.0 ...]
        end

    end

    subgraph S[Sourcetree]
        RC[releaseherald.toml\nconfiguration]
        RT["releasenote_template\n\nVersion {version_num}\n{list_of_news ...}"]
        subgraph PRN[Previous releasenotes]
            direction LR
            PRNP[#Placeholder#]
            PRN1[Version 0.7.0 ...]
            PRN2[Version 0.6.3 ...]
            PRN2[Version 0.6.0 ...]
        end
    end


    RH[Releaseherald]

    L1 --> RH
    L2 --> RH

    RC --> RH
    RT ---> RH
    PRN ---> RH

    subgraph N[New releasenotes]
        direction LR
        NRNP[#Placeholder#]
        NRN1[Version 1.0.0\nnews1\nnews2\nnews3\nnews4]
        NRN2[Version 0.9.1\nnews1\nnews2\nnews3]
        NRN3[Version 0.7.0 ...]
        NRN4[Version 0.6.3 ...]
        NRN5[Version 0.6.0 ...]
    end

    RH --> N

    N --> RE[Send in email]
    N --> RU[Add to GitHub release]
    N --> RS[Update in source and commit to git]

    style L1 fill:#f003
    style NRN1 fill:#f003
    style L2 fill:#0f03
    style NRN2 fill:#0f03Installit can be installed into the python venvpipinstallreleaseheraldor if you like it better globally, use pipxpipxinstallreleaseheraldBasicsreleaseheraldis a command line tool it needs python 3.7+ to run. It needs a config file in the root of the git repo
it should be calledreleaseherald.toml. If it is used in a python project it can read it's configuration
frompyproject.tomlfrom[tool.releaseherald]. It is possible to start without any configuration, then one needs to
create anews_fragmentdirectory in the root of the git repo and anews.rstfile which should contain a news file
something like this:Release Notes=============.. releaseherald_insertAsreleaseheraldworking with diffs between tags so if no tags yet in the repo just create one
namedRELEASEHERALD_ROOT. News fragments should be added to thenesw_fragmentdirectory, committing them, and
merged (preferably with a pull request). When releasing, a tag need to be created with
followingsemantic versioningprinciples. Once there are some commits and news fragments release
notes can be generated asreleaseherald generate. This will result something like this:Release Notes=============.. releaseherald_insert1.0.0 (2021-10-15)------------------*1, before first release*2, before first releaseThis tool try not to have many opinions, so all the above defaults can be tweaked through configuration or command line.
New fragments do not need to be removed between releases, no need to commit the generated release notes either,
asreleaseheraldworks that out from git history, though if that fits better to the workflow it can be done.