[Coco] making patches to NitrOS-9 (part II)

[David Ladd]

 On Fri, Jan 23, 2015 at 2:54 PM, Tormod Volden <lists.tormod at gmail.com>
wrote:

> (also applies to toolshed, including HDB-DOS!)
>
> With increasing activity from more contributors to the NitrOS-9 code,
> it is time for the second instalment of the "mercurial for NitrOS-9
> hackers" series. The first was... er... exactly one year ago, you
> should maybe read through it first:
>
> http://five.pairlist.net/pipermail/coco/2014-January/129654.html
>
> So you are making changes to the code and you want to share them. You
> may want to show your suggested changes to others for review and
> comments, or finally ask someone with commit rights to apply them to
> the official repository.
>
> * General Rules *
>
> First of all, when working on the code, don't just make a whole lot of
> different changes and then ask someone else to review and accept them,
> take it or leave it. That is throwing something over the wall, or
> fence. Your changes should be split up in separate patches for every
> independent change. Even if one change may depend on another, they
> should be split up (in a patch series) if they "logically" deal with
> separate issues. This makes it much easier for others to review your
> changes. It also make it easier later to track down errors which from
> time to time sneak in.
>
> Another thing is that you might want to work on your changes for a
> while, testing and improving the changes. At the same time other
> people are making their own changes, possibly to the same source file.
> Just handing out your new file version won't cut it then, if the other
> people's changes also are going to be applied. Their new file would
> overwrite your changes or vice versa. Therefore it is important to
> maintain and communicate your changes in patches, not in file
> revisions. Patch tools or software revision systems such as mercurial
> can easily combine patches that apply to the same file, as long as the
> different patches don't touch exactly the same lines.
>
> When for instance fixing a bug or changing existing code, try to
> resist the temptation to fix up white-space or e.g. comments in the
> surrounding code. It is much easier for someone else to review your
> changes if they are limited to exactly the thing they are meant to fix
> or add. White-space or other cosmetic fixes make the patch longer and
> often confusing ("why was that line changed?").
>
> The above applies to all distributed software development. So how to
> do this with mercurial? There are quick and dirty ways, and then there
> are the good ways, which with minimal practice will become your best
> friends.
>
> * The not so good way *
>
> The quick and dirty way: Make your changes, one at a time as explained
> above about separate changes. At any point you can run "hg diff" to
> see what your changes are. When one patch is ready, do "hg commit" and
> enter a comment to what your changes are doing and for what reason.
> This will be a local commit, and your local tree will diverge from the
> official repository. After a commit, "hg diff" will show you the
> change relative to your latest commit. Once you are done with your set
> of changes and want to share them, you can export your commits as text
> files, actually standard patch files.
>
> This will produce patch files from all your local commits:
> hg export -r "outgoing()" -o "%n-%m.patch"
>
> * The good way *
>
> The better way is to use a feature of mercurial called "patch queues"
> and in particular the "mq" patch system. This is implemented as an
> extension in mercurial, but one that is always included. You just need
> to enable it by adding this to your .hgrc file (in your home directory
> or in the .hg folder in your local repository):
>
> [extensions]
> mq =
>
> The patch queue is like a small repository of patches, which you can
> roll on top of your repository tree. You can roll back to a clean
> repository, for instance to sync with the official repository, then
> roll out your patches again. You can modify individual patches and
> reorder or delete them.
>
> The mq commands all start with the letter "q".
>
> Once you have done some changes, run "hg qnew my-new-fix.patch" and it
> will store your changes in the patch called my-new-fix.patch . It is
> customary to let the patch name start with a number to indicate the
> intended order of patches, but note that a number in the patch name is
> not interpreted by mq. You can rename the patch later with "hg
> qrename".
>
> If you keep on doing changes to your patch run "hg qref" to refresh
> it. You can also run "hg qref -e" to add an explanation to your
> changes. The comment will be used as a commit message later when your
> patches are finally committed. So start your comment with a short
> one-line summary, then an empty line, before you add more explanation.
> See the existing log for good and bad examples: "hg log"
>
> You can also run "hg qnew" before you make any changes, and then "hg
> qref" afterwards.
>
> "hg diff" will at any time show you the difference since the last
> commit or qref.
>
> "hg qapplied" will show your stack of patches that have been applied
> to your tree.
>
> Now comes the interesting part. You can remove the top patch from your
> tree using "hg qpop". The patch is still stored in your patch
> collection, but is no longer applied to your tree. Run "hg qpop -a" to
> pop them all off your tree. "hg qapplied" will then list none, but "hg
> qunapplied" will list all your patches.
>
> "hg qref" will always refresh the patch on top of your tree, so to
> modify a patch in the middle of your stack, just "hg qpop" until that
> particular patch is on top, make your changes and then "hg qref"
> again.
>
> You can use "hg qpush" to apply patches from the queue one by one, or
> "hg qpush -a" to apply all your patches.
>
> "hg help mq" lists all the different mq commands.
>
> This all may look complicated the first time and takes some time to
> get used to, but it will enable you to work so much better together
> with other developers and maintainers. It is actually quite useful if
> you work alone on a project too, for instance when testing out
> something temporary or something that you want to continue on later
> after finishing something else that came up.
>
> To summarize the workflow with an example:
>
> hg qnew something-I-am-working-on.patch
> (code, code, code on that)
> hg qref -e
>
> hg qnew another-thing.patch
> (code, code)
> hg qref -e
> (rework this thing a bit)
> hg qref -e
>
> Now if you want to rework the first patch:
> hg diff (to make sure there are no "unsaved" changes)
> hg qpop (play back to the first patch)
> (code, code, code)
> hg qref -e (refresh the first patch)
> hg qpush (apply second patch again)
>
> The patches are stored in the .hg/patches folder. You can pick them
> from there to send to other people etc. If another person want to
> import the patch into his patch series, he can run "hg qimport
> from-another-dev.patch".
>

​Tormod, thank you :D  This will actually help me out a lot.  Right now
what I have been doing is keeping two installs of the toolshed project.
One using the readonly download of the repo and one with the write/push
rights.  The readonly is the one I normally use to do all my testing so I
don't accidently commit and push anything. :D

Even though I do have commit rights to both toolshed and NitrOS-9 I
personally don't like to do any pushing unless it is something I know
myself works OR it is the author of something that needs their code
pushed.  To give a example of this I had found a problem with booting my
CoCoSDC with NitrOS-9 and the CoCoSDC being used in a MPI.  I talked with
Darren and he gave me updated code to fix the problem.  I then tested it
and it worked.  Then I pushed it.

Otherwise if it is something I have done myself I prefer someone else
review my work before I post it.

As far as most of the stuff I did in the past with NitrOS-9 was before
Boisy started the conversion to lwtools rather than using toolshed for
building NitrOS-9.
At that time the only reason I was on the commit rights for both of the
projects was to attempt to help fix the becker routine problem as this was
a feature I really wanted added to the emulators at the time.

Then of course I somehow started getting into dabbling in fixing some of
the 3rdparty area building issues.  Then of course Boisy asked people to
stop work on anything related with NitrOS-9 cause he was about to start the
conversion to lwtools and that was really the last time I really touched
NitrOS-9 till recently.  Just mainly because I hate stepping on toes :D

I normally don't push anything unless one I can test it OR the original
designer of a module gives me code to have pushed cause (s)he can't.

Personally there are many people in this list that have way more experience
than I do.​  One of the main reasons I use the IRC channel to talk some of
those people about whats going on in my head and ideas and how best to deal
with it.  Then of course testing it.  Then finally the final review.

Which Tormod is why I normally send you emails directly about what I have
been doing and if you feel ok about me pushing any changes I have done. :D



>
> * Final words *
>
> Use "hg diff" all the time to review your changes. If your system
> supports it, use "hg view" to browse through the commit history,
> including your patch queue, in a graphical interface.
>
> Remember when working with mercurial, help is only a "hg help" away.
> See for instance "hg help qdelete" and "hg help qpush" about its
> --move option.
>
> Regards,
> Tormod
>
> PS. For those of you with commit rights to the sourceforge
> repositories, make sure you don't inadvertently type "hg push" instead
> of "hg qpush" ! For this reason I have added this to my .hgrc:
> [hooks]
> pre-push = echo -n 'Are you sure you want to push to remote? (y/n): ';
> read reply; if test "$reply" != "y"; then echo 'Push cancelled'; exit
> 1; fi
>
> --
> Coco mailing list
> Coco at maltedmedia.com
> https://pairlist5.pair.net/mailman/listinfo/coco
>