First feedback on the GitHub usage

[Mark Taylor]

Ole's comments and suggested workflow sound very sensible to me.

On Mon, 18 Nov 2019, Ole Streicher wrote:

> Hi Laurent, all,
> 
> I think that your proposal makes it a bit too formal and complicated. In
> principle, the problem is not specific to the IVOA document creation,
> but happens everywhere.
> 
> The usual workflow (which I know from many repositories on Github,
> including astropy, sunpy, starjava, gnudatalanguage) is:
> 
> 1. When someone thinks that something is wrong with a document, but does
> not have a specific proposal (patch) to change it, it should be opened
> as an issue. This one can then be discussed in detail.
> When then someone has a specific solution, this solution goes into a
> Pull Request, mentioning the original issue with the text "Fixes: #123"
> (or whatever the issue is). This will link the two together and make
> sure that the original issue is closed once the PR is merged.
> Then one would still discuss the problem in the original issue and the
> specific solution in the pull request, linking those two together if needed.
> 
> 2. When someone just has a specific proposal, opening a separate issue
> is not required; one just opens the Pull Request. Then, everything is
> discussed there. No need to artificially separate them. I would leave it
> as a decision of the issue/PR author to decide whether they wants to
> discuss the problem separately.
> 
> One important point here is: the IVOA wants to broaden the development
> of standards and involve more people from the public. This has the
> effect that people will contribute to the development here as they do
> everywhere, and our rules shall be as close as possible to the usual way
> (f.e. in astropy) -- which means: mainly no specific rules unless they
> really arise from the specifics of the standards development.
> 
> For the same reason, I would also suggest to use the basic git workflow
> with "master" as the main development branch, and to not the "gitflow".
> The latter is just more complicated and rarely used: among the >70 git
> repositories that I use for Debian packaging I almost none uses this
> way. And all they are well-maintained, with astropy being the largest,
> very lively and brilliant example. We should just follow astropy's
> practice unless there is a really proven reason why this doesn't work
> for us.
> 
> Best regards
> 
> Ole
> 
> On 13.11.19 13:58, laurent.michel at astro.unistra.fr (Laurent Michel)
> wrote:
> > Dear VO,
> > 
> > I'm starting to use the new GitHub framework for the VO standard elaboration.
> > My current experience concerns DataLink 1.1 which is still in design phase (before WD)
> > This project is quite active these days with ~5 contributors which provides an interesting experiment of our Github standard 
> > process.
> > 
> > I would just give one personal feedback on the follow-up of the discussions we are having on Github.
> > 
> > Let's take an example of how things should work:
> > - The author A1 proposes to add the feature F to the proposal.
> > - A1 opens the issue proposing F.
> > - Another author A2 does not agree with adding F to the proposal
> > - The discussion continues on the  ISSUES panel until a compromise is reached.
> > - Finally, A1 and A2 agree on adding F' in the text
> > - A PR process can be triggered to push F'. The PR discussions are now just related to the wording of F', but no longer its 
> > relevance.
> > 
> > In the Datalink case, one PR has been open for some reason a little bit too early, therefore the discussion open on the ISSUE 
> > continued on the PR thread. This has 2 bad consequences:
> > - Followers have now to check two places (ISSUES and PR)
> > - The discussion on the PR concerns the relevance of the PR itself.
> > 
> > This example shows the necessity of clearly separate both steps (ISSUE and PR):
> > - The ISSUE tool has to be used to discuss on *what* has to be add/remove/modify on the standard
> > - The PR panel has to be used to discuss *how* to do it (e.g. wording).
> > - The PR must not be open before an agreement has been found on the ISSUE.
> > 
> > This does not relate to some Github setup but to a few good usage rules that should be promoted somehow.
> > May some people with a better Git experience than mine share their feeling about this?
> > 
> 

--
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-9288776  http://www.star.bris.ac.uk/~mbt/