First feedback on the GitHub usage

[François Bonnarel]

Hi all,

I would like to extend a little bit this discussion to wonder if github 
is the right tool to develop IVOA specifications.

I didn't know anything about github six monthes ago.

I experimented recently proposing changes for DataLink-next using github.

I found this technically more difficult than when we moved to volute. 
And I still have a lot to learn to be efficient and avoid mistakes.

There are more functionalities of course and these difficulties are the 
price to pay for that.

But I don't want to extend on this part of my experience.

But the conclusion is if we use this for specification development 
anybody proposing changes will have to learn a little bit of the git 
technology to master it.

Github is perfect for application developpers who generally are already 
used to it.

But for others ? One little example : In the current implementation you 
cannot see the result of changes accepted by the editor without cloning 
the repository and  compiling the latex yourself/

People able to write changes proposals or discussing specifications are 
not only application developper but also users, organization managers, 
service maintainers, etc...

The mailing list  /WG wiki pages / Document respository we created at 
the begining at the IVOA still seems to be the right place and way to do 
to have everybody involved in the discussions and make proposals.

I think github is probably better suited for discussion and 
collaboration between authors/editors in the intermediary phases of 
development, the stages you don't want to expose to the whole IVOA.

In that sense it seems to have much more useful functionalities than 
volute (link between issues and pull requests, control by editor, 
indexing, merging, etc..;)

But there is no possibility to reserve access to github repositories to 
a small list of people (= the authors) as far as I know.

So, I'm not really positive about moving to github in these conditions.

Cheers

François





Le 23/11/2019 à 14:16, Mark Taylor a écrit :
> 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/