Re: How to fix roundup.org's customizing.txt

* John P. Rouillard <[email protected]> [20180906 23:27]:
> 1) do nothing with the web site and leave the example in
>    customizing.txt broken. Advantage: the online doc exactly matches
>    the released doc and can be reproduced from hg. Disadvantage:
>    people looking for a working example won't find it.

Even if not good, I think this would be an acceptable solution.

> 2) check out the current customizing.txt, manually roll back the gpg
>    to pyme reference and publish.  Advantage: example works works and
>    url's to supplimentary docs also work. Disadvantage: doc not in hg,
>    doc doesn't match released 1.6.0 doc.

I don't like this due to the inconsistency, even if those who look
at the website get a better result.

> 3) branch the doc in hg (to 1.6.0_branch), roll back the gpg/pyme
>    change and publish that. Advantage: in hg and reproducable if we
>    need to do another 1.6.x release not based on trunk, working
>    example and url's.  Disadvantage: not the same as released 1.6.0,
>    need to figure out how to do the required hg work.

My suggestion here would be to to a 1.6 branch, branching off at
the 1.6.0 tag that will lead to a 1.6.1 release at some point.

Name for the branch could be maint-1.6 since we have old/closed
branches named maint-0.4 to maint-0.8.

The default branch can then continue the work on Python 3, gpg and
whatever, leading to a 1.7 (or maybe 2.0) release.

If you want to go this way, these are the required steps to to
create the new branch starting from the 1.6.0 release:

$ hg co 1.6.0
$ hg branch maint-1.6
$ hg ci -m 'created branch maint-1.6'

At this point you probably want all your changes to doc, website and
RELEASE.txt not already in the 1.6.0 release in this branch:

$ hg log doc website RELEASE.txt -r 'not ::1.6.0 and user("John Rouillard")'
changeset:   5364:dffa7d0df99c
user:        John Rouillard <[email protected]>
date:        Fri Jul 13 21:56:08 2018 -0400
summary:     Fixing links to chameleon documentation.

changeset:   5365:979390afb001
user:        John Rouillard <[email protected]>
date:        Sun Jul 15 19:54:16 2018 -0400
summary:     Fix some dev.zope.org links for tales and metal.

changeset:   5366:b87a1f51ac32
user:        John Rouillard <[email protected]>
date:        Wed Jul 18 21:31:12 2018 -0400
summary:     As far as I can tell, gmane and nabble archives are gone/not being

changeset:   5367:f3b844fda420
user:        John Rouillard <[email protected]>
date:        Wed Jul 18 21:32:24 2018 -0400
summary:     Updated links to handle:

changeset:   5374:488d44cb42ef
user:        John Rouillard <[email protected]>
date:        Fri Jul 20 22:48:48 2018 -0400
summary:     add running linkcheck to update docs

changeset:   5486:a5edd6adff14
user:        John Rouillard <[email protected]>
date:        Fri Aug 03 19:29:00 2018 -0400
summary:     Change count of number of ways to run roundup to "multiple".

changeset:   5529:0dea3d6944c5
user:        John Rouillard <[email protected]>
date:        Thu Sep 06 17:04:49 2018 -0400
summary:     'Provisional User' example needed to have search permissions added


The log option "-q" prints a short identifier that can be used
arguments in other commands:

$ hg log doc website RELEASE.txt -r 'not ::1.6.0 and user("John Rouillard")' -q
5364:dffa7d0df99c
5365:979390afb001
5366:b87a1f51ac32
5367:f3b844fda420
5374:488d44cb42ef
5486:a5edd6adff14
5529:0dea3d6944c5


The "hg graft" command can backport/cherry-pick these changes into
the new branch:

$ hg graft `hg log doc website RELEASE.txt -r 'not ::1.6.0 and user("John Rouillard")' -q`
grafting 5364:dffa7d0df99c "Fixing links to chameleon documentation."
grafting 5365:979390afb001 "Fix some dev.zope.org links for tales and metal."
grafting 5366:b87a1f51ac32 "As far as I can tell, gmane and nabble archives are gone/not being"
grafting 5367:f3b844fda420 "Updated links to handle:"
grafting 5374:488d44cb42ef "add running linkcheck to update docs"
grafting 5486:a5edd6adff14 "Change count of number of ways to run roundup to "multiple"."
grafting 5529:0dea3d6944c5 "'Provisional User' example needed to have search permissions added"
merging doc/customizing.txt


Since these 7 patches are now in the maintenance branch and the
default branch, we should do a dummy merge from maint-1.6 into
default to confirm that they already have been "merged".
This is not really needed, but if we ever intend to merge maint-1.6
in the future this will make things easier.

The internal:local merge tool prevents a 3-way-merge conflict in
RELEASE.txt by using the currently checked out version:

$ hg co default
$ hg merge --tool internal:local maint-1.6
$ hg ci -m 'mark maint-1.6 doc changes as merged'

At this point you can review your work:

$ hg show work
@    6e5b mark maint-1.6 doc changes as merged
|\
| o  6f8a (maint-1.6) 'Provisional User' example needed to have search permissions added
| o  1c41 (maint-1.6) Change count of number of ways to run roundup to "multiple".
| o  cb14 (maint-1.6) add running linkcheck to update docs
| o  b3c2 (maint-1.6) Updated links to handle:
| o  fd35 (maint-1.6) As far as I can tell, gmane and nabble archives are gone/not being
| o  229f (maint-1.6) Fix some dev.zope.org links for tales and metal.
| o  f3f8 (maint-1.6) Fixing links to chameleon documentation.
| o  e93b (maint-1.6) created branch maint-1.6
o |  0dea 'Provisional User' example needed to have search permissions added
|/
o  dc6c (1.6.0) add subhead for 1.6.0 release
|
~
o  ce06 (routing) Update router docstring to reference usage example
|
~


And finally push the new branch:

$ hg push --new-branch


In the future, when someone wants to fix something that should be
included in the 1.6.x release, the maint-1.6 branch should be
checked out:

$ hg co maint-1.6
$ $EDITOR foo.py
$ hg ci -m 'fixed serious issue in foo.py'
$ # run tests?
$ hg push

If the fix should be merged into the default branch:

$ hg co default
$ hg merge maint-1.6
$ hg ci -m 'merged fix for serious issue in foo.py'
$ # run tests?
$ hg push


And I'll be available for anything more complicated than that or if
you're running into conflicts when merging.

Regards,
Thomas

P.S.: Can anyone here tell me how above can be done with git?

-- 
Thomas Arendsen Hein <[email protected]> - OpenPGP key: 0x5BB3F5195816791A
https://blogs.intevation.de/thomas/         - https://intevation.de/~thomas/
Intevation GmbH, Neuer Graben 17, 49074 Osnabrueck - AG Osnabrueck, HR B 18998
Geschaeftsfuehrer: Frank Koormann, Bernhard Reiter, Dr. Jan-Oliver Wagner

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot

_______________________________________________
Roundup-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/roundup-devel

-----BEGIN PGP SIGNATURE-----

iF0EABECAB0WIQRT0npFua0nkV7kTt5bs/UZWBZ5GgUCW5IjsQAKCRBbs/UZWBZ5
GsdtAKCN/UsD99UMFYy05rD4l1JhsxqGqgCfbJ5eebPGh1nSdBxK2Re5PMv+83o=
=FeP+
-----END PGP SIGNATURE-----