First feedback on the GitHub usage

[Ole Streicher]

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?
>