Changes to our Git infrastructure

[Thomas Friedrichsmeier]

On Tue, 06 Jan 2015 13:19:45 +0100
Jan Kundrát <jkt at kde.org> wrote:
> On Monday, 5 January 2015 14:03:13 CEST, Thomas Friedrichsmeier wrote:
> > I think there is an easy test for this (well, not a real test, but a
> > useful initial heuristic): Can you explain exactly how to submit a
> > patch for your project
> > - to someone without prior knowledge of the tools involved
> > - without assuming the required tools/keys/accounts are already set
> > up
> > - without any further reading
> > - covering all required steps in sufficient detail
> > in no more than 2000 words, or (if it's based on a web-wizard) in
> > less than 20 minutes?
> 
> This includes links to other pages which explain how to work with
> git, but I think that it does qualify:
> 
> https://techbase.kde.org/Development/Gerrit#Getting_Started
> 
> Does it match your requirements?

It's great to see there is a starting point, but no, that's not it, yet
(and btw, I was a bit confused when calling 2.000 words the limit.
Something on the order of 500 or 600 would be more like it. So the
length of that page (the first few sections) looks ok to me, but it's
still asking a lot of prior knowledge of a _first time_ contributor.
Things I see missing:

- What exact commands do you have to run to create and enable your SSH
  key? (And will these work cross-platform?)
- What are the commands to configure name and email in git?
- When and where do I do the step of adding the gerrit remote? (And
  just in case, include the initial git clone command)
- What command(s) do I run to create a git branch? What is an example
  of a good branch name, what is bad branch name?
- Explain the basic usage of git commit, and git commit --amend.
  Including some words on what is or is not a useful commit message.
- Also explaining basic usage git diff and git status, of course, for
  verifying the commit is as desired.
- Arguably, some words on undoing undesired changes (before / after
  staging / committing (/ pushing)) would be rather needful, too.
- Might have to explain the Change-Id-thing some more (or does it
  really happen all automagically, esp. for follow-up commits)?
- I am personally unclear on whether I'd need to follow any of the
  steps after "Submitting Changes", in order to actually receive
  notifications of what happens to my request. Or how 
- Also, what is the easy / standard way to get the change in, once
  reviewed?

This may sound like nitpicking, but well, all of these are things that
you will have to know for your first review, and while many
contributors will know some of this, none of this should be assumed,
IMO.

> That page started as an attempt to provide a documentation for
> existing KDE developers, so it does go into depth of how to manualy
> Cc reviewers. If we decide to use Gerrit, then I think it would make
> a lot of sense to intorduce a single-page "Submitting Patches
> Quickstart" which would just describe the absolute basics on one
> page, including a git primer.

Absolutely. My point is: Try writing that page, and you'll get an idea
of what exactly you're asking a first timer to learn (in addition to
the coding) before they can get their first positive feedback.

And well, so I have followed you quite some way into discussing gerrit,
in particular, here. But I'd like not to go any further on this, at
this point. Let's wait for sysadmins to compile their list of
candidates (and I'd be rather sure that gerrit will be among the
candidate, at least). *Then* we can reasonably discuss the pros and cons
of specific alternatives.

Regards
Thomas
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20150106/31e9f3c4/attachment.sig>