Release notes for first version

Question

I understand what to include in ordinary release notes - there are many questions and answers relating to that.

What should I include in the first set of release notes, i.e. for the very first released version? Are release notes needed for the first version?

[Related](http://softwareengineering.stackexchange.com/questions/245240/formulate-release-notes-consistently/245251#245251) — Robbie Dee, Feb 20 '17 at 13:59
@RobbieDee Thanks, but I've already seen and upvoted that answer. It's good advice, but it's related to release notes in general, not what to do about a release note for the first release. — Amy Barrett, Feb 20 '17 at 14:05
Ah, OK. I've had a go at providing some recommendations but it could vary considerably depending on what you're writing. There is no system of weights and measures for such documents unfortunately. It is a bit fast and loose structure wise... — Robbie Dee, Feb 20 '17 at 14:20
Thanks for the answers. I'm a little unsure which to accept at the minute, so I'm going to leave it for a few days. I've upvoted you all though, as they all sound like good advice. — Amy Barrett, Feb 21 '17 at 09:20

score 10 · Accepted Answer · answered Feb 20 '17 at 12:59

Release notes (changelogs) are primarily used to notify users of changes between versions. Perhaps a new useful feature is available, or an old feature was deprecated.

The first released version has no changes. The release notes are then quite simple:

v1.0.0    2017-02-20

-  first release!

Anything else would be confusing, in my experience.

Sometimes, the v1.0 isn't the first release. This is especially the case for open-source projects where v0.x releases are common. In that case, the v1.0 release would have some changes to note. At a minimum, a v1.0 release signifies that the API is now stable, which is a noteworthy change.

For release notes on a website or a mailing list, these should be written less like a technical changelog and more like a press release. The first release is an opportunity to:

showcase why your software is awesome,
list differences to competing software, and
give an overview of your full documentation.

If your changelog is embedded into an application, the first release should probably display a “get started” guide in this space.

score 4 · Answer 2 · answered Feb 20 '17 at 14:11

While it is true that release notes only tend to appear in subsequent revisions, there is no reason why it couldn't ship with the first release.

As a minimum, you'll want the date, version number and some description - even if it is something like "Initial release".

It is perfectly possible that the initial release isn't as fully featured as was originally intended. Users may be keen to get their hands on some features and wait for others. You could therefore describe what is in the initial release and what has been parked for later.

You may also have found some issues in testing which, although they don't stop the release going out, you may want to make users aware of. These tend to be gathered under a Known issues header or such like.

You don't describe what this is for, but there may also be some software or hardware requirements.

It is important to note that the release notes should be a concise digest. If the initial version runs to a number of pages, you may simply want to point the user to the documentation.

score 2 · Answer 3 · answered Feb 20 '17 at 11:22

Would you normally include a section for "new features"?

In the first release, everything is a new feature. Make the most of it; this section will never be so large as this first one.

Your user has already bought/ downloaded the software so there's at least one feature in there that they wanted, but offering them a complete list of everything you've provided couldn't hurt either.

Release notes for first version

3 Answers3