Including the release notes in the git-1.5.0 release?

Junio,

I noticed that the file v1.5.0.txt is still in the todo branch, but not in the actual main git branch. I assume that this means you were planning on including the v1.5.0.txt in the git announcement, but not necessarily including it in the actual git 1.5.0 tarball?

As a suggestion, maybe it would be a good idea to actually include it as RELEASE-NOTES in the top-level source tree of git. This will make it much more likely that people packaging git will include in /usr/share/doc/git.

Or better yet, maybe we should include it in the Documentation directory and set it up to be built as a manpage, git-release-notes. This will make it much more likely that end users who are getting git from their Fedora, Debian, Red Hat, et. al distribution will actually see the release notes when they install the new package.

What do you think?

						- Ted

"Theodore Ts'o" <tytso@mit.edu> writes:

Indeed I was planning to use it as the announcement message, but including it in the final tarball sounds sensible.

As the text assumes familiarity with git 1.3.0 or so, I am not sure if making it as one of the manpages makes much sense.

Also there is a question of what to do when 1.6.0 comes out. Will its release notes replace 1.5.0 one? If so changes from which version will it describe?

I suspect that doing something like:

	git cat-file todo:v1.5.0.txt >Documentation/v1.5.0.txt
	ln -s Documentation/v1.5.0.txt RELEASE-NOTES
        git add RELEASE-NOTES Documentation/v1.5.0.txt

and have pointer to v1.5.0.txt from Documentation/git.txt would be a sensible and easy thing to do.

On Tue, Feb 13, 2007 at 09:44:22AM -0800, Junio C Hamano wrote:

Yeah, that's a good point.

What I've seen some projects do (including some commercial products) is to keep them around with the old file names. So if we have

Documentation/RELEASE-NOTES_1.5.0.txt Documentation/RELEASE-NOTES_1.6.0.txt Documentation/RELEASE-NOTES_1.7.0.txt

and a symlink from RELEASE-NOTES to Documentation/RELEASE-NOTES-<cur_ver>.txt

that would make a lot of sense....

The only reason why I suggest Documentation/RELEASE-NOTES_1.5.0.txt instead of Documentation/v1.5.0.txt is that it might not be as obvious what "v1.5.0.txt" is for someone just looking at it in the Documntation directory, where as "RELEASE-NOTES_1.5.0.txt leaves no doubt.

But keeping the the old release notes around is good both for people who are upgrading from older versions, and it also means that for someone who wants to answer the question, "suppose we want to enable feature <foo>", what which older versions of git clients will be breaking.

(I was about to suggest that we just break the older git clients using dumb http protecols on kernel.org, befure I realized that that meant breaking git clients that were released last August. Whoops; it's amazing how much improvements git has seen in the last six months, that it seems a lot longer ago... :-)

							- Ted

Theodore Tso <tytso@mit.edu> writes:

Done.

I used to like reading pod/perl*delta.pod but these days they are tooooo long. Hopefully we can keep our release notes short and sweet.

People might already have noticed that the latest docs at

	http://www.kernel.org/pub/software/scm/git/docs/

has link to older versions.