[Gramps-devel] 5.0.0-alpha2

[Paul Franklin]

Nick has authorized an immediate release of 5.0.0-alpha2.

In about 24 hours I (or somebody else) will be generating
the 5.0.0-alpha2 "tag" from gramps50, so if you have any
bug fixes (or bug fix pull requests) which you want to get
into 5.0.0-alpha2, please commit them (to gramps50) soon.

But don't worry about doing anything, since Nick said we'll
release "alpha3 in a couple of weeks time." (Remember we
had five "alpha" releases of 4.0.0 before its "beta" release.)

Thanks.

We could release alpha2 now and then alpha3 in a couple of weeks time.
I don't have any spare time now. You will have to organise this yourself.
Nick.

[Josip]

Post by Paul Franklin
In about 24 hours I (or somebody else) will be generating
the 5.0.0-alpha2 "tag" from gramps50, so if you have any
bug fixes (or bug fix pull requests) which you want to get
into 5.0.0-alpha2, please commit them (to gramps50) soon.

I have couple of pull requests!
Does it mean i can|should commit them myself?

[Nick Hall]

Post by Josip
I have couple of pull requests!
Does it mean i can|should commit them myself?

I can do that for you.

Nick.

[Josip]

Post by Nick Hall

Post by Josip
I have couple of pull requests!
Does it mean i can|should commit them myself?

I can do that for you.

Thanks, otherwise i don't see point of submitting pull request if
submitter will commit them himself.

[Paul Franklin]

Post by Josip
Thanks, otherwise i don't see point of submitting pull request if
submitter will commit them himself.

Some people like the Travis check which (I guess) happens
when a pull request is submitted.

[Josip]

Post by Nick Hall

Post by Josip
I have couple of pull requests!
Does it mean i can|should commit them myself?

I can do that for you.

Thank you!
For all three PR.
I see you update bug-tracker also so thanks for that too!

"Related Changesets" section in bug-tracker what is that, is it some
sort of automatic by "source integration"?

[Nick Hall]

Post by Josip
"Related Changesets" section in bug-tracker what is that, is it some
sort of automatic by "source integration"?

Yes, but it isn't quite working yet. I'll explain in another post.

Nick.

[Paul Franklin]

I've never done this before.

https://gramps-project.org/wiki/index.php?title=What_to_do_for_a_release

seems to differentiate between a "ChangeLog"
https://gramps-project.org/wiki/index.php?title=What_to_do_for_a_release#Include_ChangeLog_files

and the NEWS file
https://gramps-project.org/wiki/index.php?title=What_to_do_for_a_release#Changelog_and_NEWS_file

Are they the same? Note that the "ChangeLog" seems to /not/
be included in the "tag" (but needs to be in the tar file).

Also, several places "4.2.5.." is used. (As in "git log v4.2.5..")
What are those two dots at the end for? Are they a typo?

What is the relevance of the "4.2.5"? Is that only there in the wiki
page under the assumption that 4.2.6 will be next? It seems
to me that when I make the NEWS (and ChangeLog) for 5.0.0
(alpha2) that I need to start with everything after 4.2.0 was
branched off of the then-master. Does that make sense?

I need to figure out how to make these things, for 5.0.0-alpha2.
The wiki page seems like a summary (rather than a recipe).

Any help will be appreciated.

Thanks.

[Paul Franklin]

Post by Paul Franklin
Are they the same? Note that the "ChangeLog" seems to /not/
be included in the "tag" (but needs to be in the tar file).

Sorry. I was wrong. The wiki page /does/ say to include both
ChangeLog files in the tag.

[Paul Franklin]

Post by Paul Franklin

Post by Paul Franklin
Are they the same? Note that the "ChangeLog" seems to /not/
be included in the "tag" (but needs to be in the tar file).

Sorry. I was wrong. The wiki page /does/ say to include both
ChangeLog files in the tag.

But if I say "git checkout v4.2.5" or "git checkout 5.0.0-alpha1"
I do not see any top level "ChangeLog" (nor po/ChangeLog) file.

Should I?

[John Ralls]

Post by Paul Franklin

Post by Paul Franklin

Post by Paul Franklin
Are they the same? Note that the "ChangeLog" seems to /not/
be included in the "tag" (but needs to be in the tar file).

Sorry. I was wrong. The wiki page /does/ say to include both
ChangeLog files in the tag.

But if I say "git checkout v4.2.5" or "git checkout 5.0.0-alpha1"
I do not see any top level "ChangeLog" (nor po/ChangeLog) file.
Should I?

You should on v4.2.5, it's there on Github... but that's the *only one*. No earlier tag has a ChangeLog. However, I have a bunch of older tarballs lying around and I looked in them: From 4.1.3 back there is a ChangeLog in the tarball.

ISTR that Jérôme realized last year that the ChangeLog wasn't getting into the automatically-generated tarballs because they can only tar up what's in the repo, so he made that change on 4.2.4. The 5.0.0-alpha1 release was before that so it doesn't have a ChangeLog.

The 4.0.0 ChangeLog goes all the way back to 2002 and the 4.1.0 ChangLog goes back to the point of creating the gramps41 branch. As Noted there's no 4.2.0 ChangeLog, and the 4.2.5 one goes back only to 4.2.4. I guess you could reasonably make the 5.0.0-alpha2 ChangeLog go back to branching 4.2.0 (2b8b92da). We might want to do the same for the ChangeLog in 5.0.0 on the grounds that the alpha and beta releases will be used only by technically inclined users and won't (we hope) be in any distros.

Regards,
John Ralls

[Paul Franklin]

Post by John Ralls

Post by Paul Franklin

Post by Paul Franklin

Post by Paul Franklin
Are they the same? Note that the "ChangeLog" seems to /not/
be included in the "tag" (but needs to be in the tar file).

Sorry. I was wrong. The wiki page /does/ say to include both
ChangeLog files in the tag.

But if I say "git checkout v4.2.5" or "git checkout 5.0.0-alpha1"
I do not see any top level "ChangeLog" (nor po/ChangeLog) file.
Should I?

You should on v4.2.5, it's there on Github... but that's the *only one*. No
earlier tag has a ChangeLog. However, I have a bunch of older tarballs lying
around and I looked in them: From 4.1.3 back there is a ChangeLog in the
tarball.
ISTR that Jérôme realized last year that the ChangeLog wasn't getting into
the automatically-generated tarballs because they can only tar up what's in
the repo, so he made that change on 4.2.4. The 5.0.0-alpha1 release was
before that so it doesn't have a ChangeLog.
The 4.0.0 ChangeLog goes all the way back to 2002 and the 4.1.0 ChangLog
goes back to the point of creating the gramps41 branch. As Noted there's no
4.2.0 ChangeLog, and the 4.2.5 one goes back only to 4.2.4. I guess you
could reasonably make the 5.0.0-alpha2 ChangeLog go back to branching 4.2.0
(2b8b92da). We might want to do the same for the ChangeLog in 5.0.0 on the
grounds that the alpha and beta releases will be used only by technically
inclined users and won't (we hope) be in any distros.
Regards,
John Ralls

Your comments were very interesting John. Thanks.

Post by John Ralls

Post by Paul Franklin
But if I say "git checkout v4.2.5" or "git checkout 5.0.0-alpha1"
I do not see any top level "ChangeLog" (nor po/ChangeLog) file.
Should I?

You should on v4.2.5, it's there on Github...

Yes, I see the ChangeLog on Github, in the v4.2.5 tag.

But if I say "git checkout v4.2.5" I don't see it. Do you?

The only "ChangeLog" is help/ChangeLog and seems to
be from 2008 (do we really need that around anymore?).


I asked about the "v4.2.5.." in the wiki page and thanks to
"man gitrevisions" I now know it is the same as "v4.2.5..HEAD"
and asks "what's happened since the v4.2.5 branch was forked
off?"

I haven't made the 5.0.0-alpha2 tag yet.

However, I have decided to make both ChangeLog files by
following the exact command lines shown on the wiki page.
(I don't plan to do any editing of the results since I don't think
they matter, and are mainly there to fulfill a legal requirement.
The "git2cl" Perl script seems not to have been updated for
almost ten years for instance.)

The NEWS file is a different story. I am working on making
that one. I plan to "go back to branching 4.2.0" but I used a
different commit (546a53e6 instead of your 2b8b92da). I am
currently working on editing the 3200 subject lines this made:

git log 546a53e6.. --no-merges --format='* %s'

(removing bug numbers, p.r. numbers, developer-only messages,
and making a guess about what developer-based enhancement
messages to leave in).

It's somewhat tedious but (I am guessing) it'll be just this once.

[John Ralls]

Post by Paul Franklin

Post by John Ralls

Post by Paul Franklin

Post by Paul Franklin

Post by Paul Franklin
Are they the same? Note that the "ChangeLog" seems to /not/
be included in the "tag" (but needs to be in the tar file).

Sorry. I was wrong. The wiki page /does/ say to include both
ChangeLog files in the tag.

But if I say "git checkout v4.2.5" or "git checkout 5.0.0-alpha1"
I do not see any top level "ChangeLog" (nor po/ChangeLog) file.
Should I?

You should on v4.2.5, it's there on Github... but that's the *only one*. No
earlier tag has a ChangeLog. However, I have a bunch of older tarballs lying
around and I looked in them: From 4.1.3 back there is a ChangeLog in the
tarball.
ISTR that Jérôme realized last year that the ChangeLog wasn't getting into
the automatically-generated tarballs because they can only tar up what's in
the repo, so he made that change on 4.2.4. The 5.0.0-alpha1 release was
before that so it doesn't have a ChangeLog.
The 4.0.0 ChangeLog goes all the way back to 2002 and the 4.1.0 ChangLog
goes back to the point of creating the gramps41 branch. As Noted there's no
4.2.0 ChangeLog, and the 4.2.5 one goes back only to 4.2.4. I guess you
could reasonably make the 5.0.0-alpha2 ChangeLog go back to branching 4.2.0
(2b8b92da). We might want to do the same for the ChangeLog in 5.0.0 on the
grounds that the alpha and beta releases will be used only by technically
inclined users and won't (we hope) be in any distros.
Regards,
John Ralls

Your comments were very interesting John. Thanks.

Post by John Ralls

Post by Paul Franklin
But if I say "git checkout v4.2.5" or "git checkout 5.0.0-alpha1"
I do not see any top level "ChangeLog" (nor po/ChangeLog) file.
Should I?

You should on v4.2.5, it's there on Github...

Yes, I see the ChangeLog on Github, in the v4.2.5 tag.
But if I say "git checkout v4.2.5" I don't see it. Do you?
The only "ChangeLog" is help/ChangeLog and seems to
be from 2008 (do we really need that around anymore?).
I asked about the "v4.2.5.." in the wiki page and thanks to
"man gitrevisions" I now know it is the same as "v4.2.5..HEAD"
and asks "what's happened since the v4.2.5 branch was forked
off?"
I haven't made the 5.0.0-alpha2 tag yet.
However, I have decided to make both ChangeLog files by
following the exact command lines shown on the wiki page.
(I don't plan to do any editing of the results since I don't think
they matter, and are mainly there to fulfill a legal requirement.
The "git2cl" Perl script seems not to have been updated for
almost ten years for instance.)
The NEWS file is a different story. I am working on making
that one. I plan to "go back to branching 4.2.0" but I used a
different commit (546a53e6 instead of your 2b8b92da). I am
git log 546a53e6.. --no-merges --format='* %s'
(removing bug numbers, p.r. numbers, developer-only messages,
and making a guess about what developer-based enhancement
messages to leave in).
It's somewhat tedious but (I am guessing) it'll be just this once.

I didn't, but after deleting the tag in my local repo and `git pull --tags` now I do. It was re-tagged after Jérôme added the ChangeLog. History looks a bit strange because you seem to have had two separate gramps42 branches that you merged and pushed on 17 December. See 2bd1a4b7.

IMO you should leave bug numbers in the NEWS file. Fixed bugs are perhaps the second-most interesting thing after new features. When releasing GnuCash I also prune out minor changes as not being "newsworthy".

Regards,
John Ralls

[Paul Franklin]

Post by John Ralls
IMO you should leave bug numbers in the NEWS file. Fixed bugs are perhaps
the second-most interesting thing after new features. When releasing GnuCash
I also prune out minor changes as not being "newsworthy".

Well, I'll think about it. Thanks for the suggestion.

I'm about a thousand lines into the three thousand. 8-(

(So it's going through those thousand again vs. more work
on the two thousand remaining. What a choice. Note that
it would be a change from what we have been doing. When I
looked at the NEWS in gramps42 I had to go back to the 3.1.1
release before I saw any bug numbers.)

I /really/ wish we had a "style guide" (or something) that said
what to purge and what to keep, when the "git log" output is
used to make a "NEWS" file prototype.

The corollary is that then (maybe, I hope,) we could somehow
flag each commit subject line with a flag, or one of a set of them,
such that their editing could be automated as much as possible.

(I have a hunch that Jerome would have liked that some years ago!)

I am purging anything which strikes me as developer-only (like
"delete the so-and-so method" -- and a lot of DBAPI commits,
plus the obvious things like unittest and pylint commits).

But I am also deleting all the "translation" commit messages,
as Jerome just summarized them at the end of a release section.

Maybe I'll take a break for some hours, rest my butt and see
if any other developers have any opinions about this.

(For instance I have thought of just putting in the "raw" output
from the "git log" command, on the theory that this "alpha2"
release is only temporary. There will be an alpha3 "in a few
weeks" and maybe some consensus or resolution or whatever
might have happened by then, about this stuff.)

[Paul Franklin]

Post by Paul Franklin

Post by John Ralls
IMO you should leave bug numbers in the NEWS file. Fixed bugs are perhaps
the second-most interesting thing after new features. When releasing GnuCash
I also prune out minor changes as not being "newsworthy".

Well, I'll think about it. Thanks for the suggestion.

It could be argued that what you suggest won't be possible
in the future, since as of the recent implementation and/or
linkage of the bug tracker and github, as I understand it,
bug numbers will no longer be in the first/subject line (as
they used to be). Instead they will be in the second line,
or at the end of the remaining lines, if any. "Fixes #12345"
for instance.

So I'll let you and Nick discuss what is preferable, I guess.

[Paul Franklin]

Post by Paul Franklin
I'm about a thousand lines into the three thousand. 8-(
I /really/ wish we had a "style guide" (or something) that said
what to purge and what to keep, when the "git log" output is
used to make a "NEWS" file prototype.
The corollary is that then (maybe, I hope,) we could somehow
flag each commit subject line with a flag, or one of a set of them,
such that their editing could be automated as much as possible.

I am essentially hand-editing a 60-page (of 50-lines, single-spaced)
document. There's a lot to be said for automating as much of that
as possible, even if it does happen only every year (or two).

[John Ralls]

Nick,

Paul just asked me a question about https://gramps-project.org/wiki/index.php?title=What_to_do_for_a_release which got me to look at the procedure. It looks a bit out of order to me.

Tagging a commit causes the creation of a release on Github, including generating tarballs, so that should be the last step. Git isn't subversion, so tags and branches are not the same thing, and creating a branch for a release isn't useful: Once the release is made there's no further work to do on it.

So the procedure should be:
0. Run `git pull --rebase` to make sure that your local repo is up-to-date.
1. Run `git status` and check the untracked files to make sure that there's nothing important that needs to be added to the repo. Run `git clean -fdx` to get rid of all untracked files.
2. Build and test to make sure that the release will work.
3. Comment out the line VERSION += git_revision in gramps/gen/const.py.
4. Generate the ChangeLog and NEWS files. If it's a new branch, add them and update Manifest.in to include them. Commit.
5. Run `python3 setup.py dist` to create the official tarball.
6. Run `git pull --rebase` again to make sure that no one has made any commits while you were working. If there are new commits, add them to ChangeLog and News and amend the commit.
7. Tag the commit with the release number (e.g. v5.0.0-alpha2)
8. Push to Github.
9. Open the release on Github, create the release announcement. Publish the release.
10. Create the release directory on SourceForge and upload the tarball.
11. Announce the release.
12. Bump the version number in version.py, uncomment the git_revision line in const.py, commit and push.

Regards,
John Ralls

[Paul Franklin]

Hi Nick,

Now that John has changed the instructions, I am even
more scared than before about making the release.

So I have (I think) committed the new NEWS file, and
the two new ChangeLog files (and MANIFEST.in), and
the two changed version files -- all to maintenance/gramps50.

It took me several tries to get that far, and apparently one
of my earlier tries, when I was following the wiki and making
the new tag (early), got saved, so that when I did the upload
it also (I think) uploaded the new 5.0.0-alpha2 tag. (But I do
not see it in the github Dashboard so maybe I am wrong.)

Anyway, I am writing to ask if you have the time to do the
rest of the release?

[Paul Franklin]

My guess is that Nick (and John and Jerome) don't have time
right now, to either finish the "github stage" of the release or
to update the wiki page so that even a novice git user (me)
can do it.

Does anybody else understand git better than I do and want
to take a stab at doing it, reading the old wiki instructions
and John's updated draft instructions, then following them?

My gut feeling is that most of the "hard" (non-git) work has
been done already, if that helps. But given that I have made
mistakes doing git things I am unfamiliar with (like merging
in a pull request and uploading it, which I won't try again),
I am reluctant to try to understand John's draft well enough
to try doing it -- especially when perhaps nobody like Nick
or John is around to be able to correct any error I make.

Any volunteers?

[Josip]

Post by Paul Franklin
My guess is that Nick (and John and Jerome) don't have time
right now, to either finish the "github stage" of the release or
to update the wiki page so that even a novice git user (me)
can do it.
Does anybody else understand git better than I do and want
to take a stab at doing it, reading the old wiki instructions
and John's updated draft instructions, then following them?
My gut feeling is that most of the "hard" (non-git) work has
been done already, if that helps. But given that I have made
mistakes doing git things I am unfamiliar with (like merging
in a pull request and uploading it, which I won't try again),
I am reluctant to try to understand John's draft well enough
to try doing it -- especially when perhaps nobody like Nick
or John is around to be able to correct any error I make.
Any volunteers?

This is a "pre-release" not meant for normal using so why not keep
things simple as possible.

I don't see why you add line in const.py:
VERSION += "-1"
instead of:
#VERSION += git_revision

I made alpha2 tag, you can remove it if you wish

[Paul Franklin]

Thanks for doing the github release of 5.0.0-alpha2, Josip!

Post by Josip
This is a "pre-release" not meant for normal using so why not keep
things simple as possible.

Sounds like a fine idea to me!

(For instance, only after I'd made the NEWS file did I
notice there was no NEWS section for 5.0.0-alpha1 in
that release. So as far as I am concerned, I think the
wiki page should be augmented to say things like that,
explicitly document what steps may be skipped for an
alpha or beta release. So that people unfamiliar with it
(like me) know what to do.)

(And I notice the wiki's News and Headline News sections
only have the 4.2.5 release, whereas the "previous releases"
page does have a 5.0.0-alpha1 entry.)

Post by Josip
VERSION += "-1"
#VERSION += git_revision

Well, I had to /guess/ what to do for the "-1", since
the (old 12/2016) wiki page didn't explicitly say:

https://github.com/gramps-project/gramps/commit/a97c20f4b5cb6d240d968198a6100109f660c3b4

I was thinking that if I blew it then a 5.0.0-alpha2-2
tar file (or whatever) would be possible. Maybe that
doesn't make sense? (Whatever, the wiki page should
say what to do, if anything, IMHO.) Personally, I don't
see why there is /both/ version.py and also const.py,
splitting the things which need to change for a release.

The wiki page hasn't been updated yet, based on the
suggestions John made (or whatever you did, Josip).

I am curious though. Did you just let github (I guess)
make the tar.gz file, or did you make it by running the
"python3 setup.py sdist" that the wiki page says (or the
"python3 setup.py dist" which John's draft mentioned)?

Once again, thanks for finishing what I started, Josip!

[Josip]

Post by Paul Franklin
Thanks for doing the github release of 5.0.0-alpha2, Josip!

Post by Josip
This is a "pre-release" not meant for normal using so why not keep
things simple as possible.

Sounds like a fine idea to me!
(For instance, only after I'd made the NEWS file did I
notice there was no NEWS section for 5.0.0-alpha1 in
that release. So as far as I am concerned, I think the
wiki page should be augmented to say things like that,
explicitly document what steps may be skipped for an
alpha or beta release. So that people unfamiliar with it
(like me) know what to do.)
(And I notice the wiki's News and Headline News sections
only have the 4.2.5 release, whereas the "previous releases"
page does have a 5.0.0-alpha1 entry.)

Added 5.0.0-alpha2 entry to the "previous releases".

Post by Paul Franklin

Post by Josip
VERSION += "-1"
#VERSION += git_revision

Well, I had to /guess/ what to do for the "-1", since
https://github.com/gramps-project/gramps/commit/a97c20f4b5cb6d240d968198a6100109f660c3b4
I was thinking that if I blew it then a 5.0.0-alpha2-2
tar file (or whatever) would be possible. Maybe that
doesn't make sense? (Whatever, the wiki page should
say what to do, if anything, IMHO.) Personally, I don't
see why there is /both/ version.py and also const.py,
splitting the things which need to change for a release.

But if something gets wrong and you want to make 5.0.0-alpha2-2 then you
need to change it to "-2" in new commit and that commit will be newer
then the one which is taged as alpha2.

That line should be commented out on release just as
"What_to_do_for_a_release" page says as is only usable to people running
gramps from git.

Post by Paul Franklin
The wiki page hasn't been updated yet, based on the
suggestions John made (or whatever you did, Josip).

I just do change mentioned above in ecf02a02 and pushed it,
then tag this commit with:
git tag -a v5.0.0-alpha2 ecf02a02
then pushed this tag:
git push origin v5.0.0-alpha2
(By default, the git push command doesn’t transfer tags to remote
servers. You will have to explicitly push tags to a shared server after
you have created them)

Post by Paul Franklin
I am curious though. Did you just let github (I guess)
make the tar.gz file, or did you make it by running the
"python3 setup.py sdist" that the wiki page says (or the
"python3 setup.py dist" which John's draft mentioned)?

They are made by github.

Post by Paul Franklin
Once again, thanks for finishing what I started, Josip!

[Paul Franklin]

Post by Josip

Post by Paul Franklin
(And I notice the wiki's News and Headline News sections
only have the 4.2.5 release, whereas the "previous releases"
page does have a 5.0.0-alpha1 entry.)

Added 5.0.0-alpha2 entry to the "previous releases".

Thank you.

[Nick Hall]

Post by John Ralls
Tagging a commit causes the creation of a release on Github, including generating tarballs, so that should be the last step. Git isn't subversion, so tags and branches are not the same thing, and creating a branch for a release isn't useful: Once the release is made there's no further work to do on it.

OK. Will you update the wiki?

Nick.