Basic

Pre-releases and the gap

Between two releases there is a period where the code is changing and something is being tested. Naming that period is what makes it visible, because an unnamed one is a version that exists in the world and appears in no history.

What you will see

A suffix that says this build may change, which is what keeps a report against it traceable.

About 1 min of reading

Try It

Name the candidate.

1

The tag

git tag -a v2.5.0-rc1 -m 'candidate, not shipped'

Before you run it, say out loud what it will print. Then open the answer.

What it prints
A suffix that says this build may change, which is what keeps a report against it traceable.

Data Flow

A candidate is a named build.
1 Build the candidate
↓
2 Name it with a suffix
↓
3 Test it as itself
↓
4 Ship the release separately
Why this works
Freeze the candidate

Once a candidate is built, changes go to the next candidate, not into it. Editing a shipped candidate is what makes a version number mean two different things.

Say what is not yet in it

A candidate lists what it does not have compared to the planned release. That list is what a tester uses to know their results are about the release, not the candidate.

Examples

The candidate

2.5.0-rc1 is a build that may still change. Anyone running it knows they are not on the release, and that knowledge is what prevents a bug report against a version that will not exist.

The gap in the wild

Users on 2.3 while the team builds 2.5. That gap is where the complaints come from, and a changelog that lists only 2.5 does not help them.

Do not skip the note

A release that fixes something a pre-release shipped needs a line saying so. Otherwise a person who hit it in the candidate searches a changelog and finds nothing.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← Writing a changelog
Previous Lesson
Writing a changelog
Next Lesson
Pinning a version
Pinning a version →