Patch preparation for GSoC evaluation

[Christian Mauderer]

Am 11.08.2017 um 12:14 schrieb Denis Obrezkov:
> 2017-08-11 11:53 GMT+02:00 Sebastian Huber
> <sebastian.huber at embedded-brains.de
> <mailto:sebastian.huber at embedded-brains.de>>:
> 
>     On 11/08/17 11:44, Denis Obrezkov wrote:
> 
>         during our last meeting I didn't completely understand what to do
>         with my commits.
> 
>         I have a set of commits made during the GSoC, they are, of course,
>         a bit chaotic. And the only last few commits make my code look
>         better.
>         So, I have a question: should I take all my commits,
>         merge them into one big commit which changes the state of the code
>         from the initial to the current state? Or how should I clean my
>         commit history?
> 
> 
>     Ideally, there should be a patch set, that can be integrated into
>     RTEMS with clean, self-contained, well described and easy to review
>     patches.
> 
>     -- 
>     Sebastian Huber, embedded brains GmbH
> 
>     Address : Dornierstr. 4, D-82178 Puchheim, Germany
>     Phone   : +49 89 189 47 41-16 <tel:%2B49%2089%20189%2047%2041-16>
>     Fax     : +49 89 189 47 41-09 <tel:%2B49%2089%20189%2047%2041-09>
>     E-Mail  : sebastian.huber at embedded-brains.de
>     <mailto:sebastian.huber at embedded-brains.de>
>     PGP     : Public key available on request.
> 
>     Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
> 
> 
> Would it be appropriate to provide a set of patches, for example,
> for uart, clock and linkcmd related code, but without saving a commit
> history?
> I mean - to make a git reset --mixed and then make new commits with
> relatively 
> clean code.
> > --
> Regards, Denis Obrezkov
> 

Hello Denis,

if I understood you correct, that would be the right form for your
patches. Just remember that you must never change a commit that is
already in the public master branch. So as long as you are in your own
development repository you can merge patches. Like Sebastian said, the
final patches should be compilable, readable and contain only one feature.

It's good practice to do the rework of the patches on an extra branch or
rename the old branch so that it is still there for reference.

Let me shortly describe my typical workflow. Maybe that makes it clear:

If I implement a new feature, the first for me is to create a branch. If
you haven't done that, that is no problem. Then your branch is just your
local "master".

I then make a lot of intermediate commits. Most of the time, the commit
message is just a rough note for myself, what I have done. Often it's
quite short. Something like "FIXME: Partial function xyz()." If you
would check out any of them, a lot wouldn't even compile.

As soon as my feature is done, I create a new branch from that (so I can
keep the old for backup) and then I start to reorder and squash the
commits on this new branch together. My preferred method for that is a
"git rebase origin/master" (or on top of the commit before I branched
the feature). If something goes wrong during the rebase (which happens
more often then I would like) I just check out my old backup branch and
do the rebase again.

Most of the time, I check the result of the rebase with a "git diff
my-old-branch" to make sure I didn't loose any changes.

After the rebase, I have only very few (often only one or two) commits
left. All of these commits should be compilable. Every commit contains a
set of changes that belongs together. It's quite possible that it is
only one patch that adds exactly one driver without the whole history
how I developed that driver. That patch will be sent to the mailing list.

That works quite well for a feature that is developed by a single
person. There are some other cases too:

If you imported some files from other sources, you should check in these
sources unchanged in one commit (ideally don't add them to a Makefile or
similar so that the whole tree is still compilable) and then add your
changes and enable the compile process in a separate one. So it is easy
to see what has been changed and maybe update to a more recent version
of the original sources.

If someone provided parts of the development, you should handle the
commits of that person in a way that the author is still clearly stated.

I'm sure there are a lot of other edge cases. But these two are the most
common ones for me.

Please don't hesitate to ask if something isn't clear.

Kind regards

Christian Mauderer