view release on metacpan or  search on metacpan

CONTRIBUTING  view on Meta::CPAN

The recommended path uses the C<git-flow> CLI (C<git-flow-avh>) to drive the
ceremony. Plain C<git> works too — both variants are shown side-by-side at
each step so you can pick one.

The release pipeline itself is fully automated by
F<.github/workflows/release.yml>: pushing any C<v*> tag triggers a build, a
PAUSE upload, and a GitHub Release with the tarball attached. You only need
to drive the local prep and the merge/tag.

=head2 Prerequisites (one-time)

=over 4

=item 1. Install release tooling

    # POD → Markdown converter (regenerates README.md)
    cpanm Pod::Markdown
    # or: apt install libpod-markdown-perl

    # Conventional-Commits changelog generator
    cargo install git-cliff
    # or: brew install git-cliff

    # git-flow CLI (optional but recommended)
    apt install git-flow
    # or: brew install git-flow-avh

=item 2. Initialize git-flow once (skip if you prefer plain git)

    git flow init -d

When prompted, accept the project's existing layout:

=over 4

=item *

production branch = C<main>

=item *

next-release branch = C<devel>

=item *

feature prefix = C<feat/>

=item *

release prefix = C<release/>

=item *

hotfix prefix = C<hotfix/>

=back

The C<-d> flag uses defaults where they match; you'll only be prompted for
the values that differ.

=item 3. Configure CPAN credentials (repo admin, one-time)

In GitHub, go to B<Settings → Secrets and variables → Actions> and add:

=over 4

=item *

C<PAUSE_USER> — your PAUSE username

=item *

C<PAUSE_PASSWORD> — your PAUSE password

=back

If these secrets are missing, the GitHub Release step still runs but the
PAUSE upload step is skipped.

=back

=head2 Versioning convention

C<$VERSION> uses the 3-digit C<0.XYZ> form. Bump the last two digits
in steps of 10 for normal releases (e.g. C<0.350 → 0.360>) and by 1 for
pure bug-fix follow-ups (e.g. C<0.350 → 0.351>). The git tag prepends
C<v> (e.g. C<v0.360>); the C<$VERSION> string in the F<.pm> does not.

=head2 Bumping the version

Use the F<tools/bump-version> helper rather than hand-editing the
fifteen C<our $VERSION = "..."> declarations under F<lib/>. Pass the
new version as the only argument:

    tools/bump-version 0.402

The script:

=over 4

=item *

Reads the current dist version from F<lib/GDPR/IAB/TCFv2.pm> and
refuses to run if the new version is not strictly greater (the same
sanity check PAUSE itself enforces against version regressions).

=item *

Rewrites C<our $VERSION = "..."> in every F<lib/**/*.pm> file in
place.

=item *

Refuses to run if any F<.pm> under F<lib/> is missing the
C<$VERSION> declaration entirely. That signals either a new module
that was added without seeding C<$VERSION>, or a drift caused by
hand-editing. Investigate and reconcile before bumping.

=back

The script does B<not> touch F<CHANGELOG.md>, run C<git cliff>,