TechBase git policies, infrastructure documentation, please

[Stephen Kelly]

Alexander Neundorf wrote:

> On Sunday 29 April 2012, Stephen Kelly wrote:
>> Alexander Neundorf wrote:
>> > git is a powerful tool, and you can use it in many different ways. It
>> > needs to be easy to find out how git is intended to be used in KDE. I
>> > don't know where this is documented. I expect this on techbase.
>> 
>> It is indeed not on techbase as far as I can see too.
>> 
>> Do you have specific questions?
>> 
>> Are you looking for tutorials on how to use git generally (not KDE
>> specific),
> 
> I kind of manage to get along with it in the mean time, if I know what I
> should do.
> 
> Ok, here's a question: I'd like to modify the buildsystem for
> kdelibs/tier1/itemmodels/, but in some branch so others can have a look at
> it. What is the recommended way to do this ?

It this specific case, it's likely that the whole of what you want to change 
and have reviewed can be shown as one single patch (even if you split it 
into multiple patches when you commit). 

The cases where it takes more than one patch, that is also easiest (for me 
at least) as just creating a file with the patches and sending it with 
email. Reviewboard is only practical for one patch at a time afaik, but I'm 
not a Reviewboard fan anyway.

> 
>> or are you looking for policies (KDE specific)?
> 
> This one.
> What is the git workflow/are the git workflows to use in KDE.
> Including use cases like doing minor fixes, normal feature development,
> experimental stuff to show somebody, etc.
> 
> Ideally including the typical git commands to use for that.


Assuming you know how to make commits and assuming you start with a clean 
checkout:

vi tier1/itemmodels/CMakeLists.txt
# ...
git commit -m "lorem ipsum"
vi tier1/itemmodels/CMakeLists.txt
# ...
git commit -m "prink the retjuts"
vi tier1/itemmodels/CMakeLists.txt
# ...
git commit -m "unfubar the dolors"

Then 

git format-patch --stdout origin/frameworks

will print out the patches and commit messages. Redirect it to a file and 
send the file for review.

Then someone will give feedback and might say that there is a small change 
needed to the first patch (the "lorem ipsum" one).

You do this:

git rebase -i origin/master

You see this with some instructions:

pick 514c03d lorem ipsum
pick 2ab30eb prink the retjuts
pick 9266e12 unfubar the dolors

you replace 'pick' with 'edit' in your editor, save and exit.

You make the change suggested in the review.

You use:

git commit --ammend

Then 

git rebase --continue

Then use gitk and you will see that the lorem ipsum commit now has your 
change.

http://book.git-scm.com/4_interactive_rebasing.html

Google 'interactive rebase' for more.

Then when you push, you might get this:

To git at git.kde.org:kdelibs
 ! [rejected]        frameworks -> frameworks (non-fast-forward)
error: failed to push some refs to 'git at git.kde.org:kdelibs'
To prevent you from losing history, non-fast-forward updates were rejected
Merge the remote changes (e.g. 'git pull') before pushing again.  See the
'Note about fast-forwards' section of 'git push --help' for details.

Just do this:

git pull --rebase

Then git push again.

> If we have multiple recommended workflows, it would be really good to have
> an overview where I can see which workflow should be used where.
> 
> E.g. below you describe what should be done in kdelibs.
> Now if I want to fix something e.g. in kdegames, where do I find out what
> workflow should be used there.

You look in gitk and see what the people do. If people commit directly to 
the branch you want to commit to, you do the same. It would be unusual for 
that not to be the case, so just assume that you always just make commits, 
rebase/rewrite them until they are correct, git pull --rebase, and then git 
push.

> This should be on techbase.
> 
> Did we settle on the branch names ? Is this documented on techbase, in the
> git section ?

To keep useful history, don't push work branches to kdelibs.git. Instead 
push to a scratch repo, ask for reviews of that branch, and when it's ready, 
rebase it to master in kdelibs.git, and push that.

http://community.kde.org/Sysadmin/GitKdeOrgManual#Personal_scratch_repositories

> Having it somewhere in a blog is only slightly better than nothing.
> 
> KDE should have a place where you can easily find how to start
> development. While with cvs and svn there is mostly one way to use
> branches etc., with git you can do whatever you want, and we don't have
> this documented.
> 
> E.g for CMake itself this is documented here:
> http://www.cmake.org/Wiki/CMake/Git
> 
> Something similar for KDE is missing, at least on techbase.
> 
> Alex
> 
> P.S. Stephen, you're doing great work on KDE frameworks :-)

Thanks, :)