<div dir="ltr"><div dir="ltr"><div class="gmail_default" style="font-size:small"><br></div><div class="gmail_default" style="font-size:small">Comments injected below to retain some context.</div><div class="gmail_default" style="font-size:small"><br clear="all"></div><div><div dir="ltr" class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div><div>--<br></div><div>Patrick Dowler<br></div>Canadian Astronomy Data Centre<br></div>Victoria, BC, Canada<br></div></div></div></div></div><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, 29 Nov 2019 at 09:45, François Bonnarel <<a href="mailto:francois.bonnarel@astro.unistra.fr">francois.bonnarel@astro.unistra.fr</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I experimented recently proposing changes for DataLink-next using github<span class="gmail_default" style="font-size:small">.</span><br>
I found this technically more difficult than when we moved to volute. <br></blockquote><div><br></div><div style="font-size:small" class="gmail_default">I think feedback via mailing lists and wiki pages like DataLink_next still have their place for the community to provide input (see below).</div><div style="font-size:small" class="gmail_default"><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
And I still have a lot to learn to be efficient and avoid mistakes.<br>
<br>
There are more functionalities of course and these difficulties are the <br>
price to pay for that.<br></blockquote><div><span class="gmail_default" style="font-size:small">Yeah, there is more tech and there is a learning curve to become reasonably efficient at using github to collaborate.</span></div><div><span class="gmail_default" style="font-size:small"></span> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
But the conclusion is if we use this for specification development <br>
anybody proposing changes will have to learn a little bit of the git <br>
technology to master it.<br>
<br>
Github is perfect for application developpers who generally are already <br>
used to it.<br>
<br>
But for others ? One little example : In the current implementation you <br>
cannot see the result of changes accepted by the editor without cloning <br>
the repository and compiling the latex yourself/<br></blockquote><div><span class="gmail_default" style="font-size:small">Well, a merge in github is like a commit on volute: neither magically makes a readable pdf or html document that others can find and read and someone or some process has to do that and publish the result. For volute, that's </span> <span class="gmail_default" style="font-size:small">a WG chair or vice chair doing "svn update" and "make" and uoload-to-doc-repo... </span></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
People able to write changes proposals or discussing specifications are <br>
not only application developper but also users, organization managers, <br>
service maintainers, etc...<br>
<br>
The mailing list /WG wiki pages / Document respository we created at <br>
the begining at the IVOA still seems to be the right place and way to do <br>
to have everybody involved in the discussions and make proposals.<br></blockquote><div><span class="gmail_default" style="font-size:small"><br></span></div><div><span class="gmail_default" style="font-size:small"></span></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I think github is probably better suited for discussion and <br>
collaboration between authors/editors in the intermediary phases of <br>
development, the stages you don't want to expose to the whole IVOA.<br></blockquote><div><br></div><div style="font-size:small" class="gmail_default">I completely agree that the mailing lists and wiki pages (especially Something_next) are the places to collect feedback from a wide range of users of a standard.Github issues aren't the right tool for this kind of feedback. More technical things like "this part of the spec and that example are inconsistent" are issues that can be analysed and dealt with in isolation. Once a new use case/requirement is well understood, then it could be the subject of an issue and authors can figure out a solution. It is usually the case that people come with feedback that combines a new use case/ requirements, and solutions and they may have implemented some/all of the solution.... <br></div><div style="font-size:small" class="gmail_default"></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
In that sense it seems to have much more useful functionalities than <br>
volute (link between issues and pull requests, control by editor, <br>
indexing, merging, etc..;)<br>
<br>
But there is no possibility to reserve access to github repositories to <br>
a small list of people (= the authors) as far as I know.<br></blockquote><div><br></div><div style="font-size:small" class="gmail_default">While I agree that it will usually be authors and editors working in github, we do get contributions from other people. Usually that's people who are authors of other standards that know how to do the technical steps and I recall this with spelling and typos and they defer content changes to the authors... that happened with volute and can still happen with github. <br></div><div style="font-size:small" class="gmail_default"><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
So, I'm not really positive about moving to github in these conditions.<br>
<br></blockquote><div><br></div><div><div style="font-size:small" class="gmail_default">I guess all I can say here is that I agree with everything you said and maybe the only "issue" is that github was seen/expected/presented/sold as the bug magic replacement for everything that was going to make it all better and we'd be able to produce new standards in a few months. Of course, it doesn't do that at all -- we all still have to do the real hard work and github can help with a portion of it. From my point of view, it helps with (i) track things we agreed to do or change, (ii) accept implementation of those changes, (iii) review the implemented changes. It is not far off to be able to (iv) automate testing that changes did not break the document build, (v) automate publish the latest cutting edge document where everyone can see it*, and (vi) automate publishing to the IVOA doc repo under some condition (maybe something like tagging the repo as WD-Foo-1.1-20191225).</div><div style="font-size:small" class="gmail_default"><br></div><div style="font-size:small" class="gmail_default">* shouldn't be too hard to push it to the WG wiki page, for example</div><div style="font-size:small" class="gmail_default"><br></div><div style="font-size:small" class="gmail_default">Sincerely,</div><div style="font-size:small" class="gmail_default"><br></div><div style="font-size:small" class="gmail_default">Pat<br></div><div style="font-size:small" class="gmail_default"><br></div></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
<br>
<br>
<br>
Le 23/11/2019 à 14:16, Mark Taylor a écrit :<br>
> Ole's comments and suggested workflow sound very sensible to me.<br>
><br>
> On Mon, 18 Nov 2019, Ole Streicher wrote:<br>
><br>
>> Hi Laurent, all,<br>
>><br>
>> I think that your proposal makes it a bit too formal and complicated. In<br>
>> principle, the problem is not specific to the IVOA document creation,<br>
>> but happens everywhere.<br>
>><br>
>> The usual workflow (which I know from many repositories on Github,<br>
>> including astropy, sunpy, starjava, gnudatalanguage) is:<br>
>><br>
>> 1. When someone thinks that something is wrong with a document, but does<br>
>> not have a specific proposal (patch) to change it, it should be opened<br>
>> as an issue. This one can then be discussed in detail.<br>
>> When then someone has a specific solution, this solution goes into a<br>
>> Pull Request, mentioning the original issue with the text "Fixes: #123"<br>
>> (or whatever the issue is). This will link the two together and make<br>
>> sure that the original issue is closed once the PR is merged.<br>
>> Then one would still discuss the problem in the original issue and the<br>
>> specific solution in the pull request, linking those two together if needed.<br>
>><br>
>> 2. When someone just has a specific proposal, opening a separate issue<br>
>> is not required; one just opens the Pull Request. Then, everything is<br>
>> discussed there. No need to artificially separate them. I would leave it<br>
>> as a decision of the issue/PR author to decide whether they wants to<br>
>> discuss the problem separately.<br>
>><br>
>> One important point here is: the IVOA wants to broaden the development<br>
>> of standards and involve more people from the public. This has the<br>
>> effect that people will contribute to the development here as they do<br>
>> everywhere, and our rules shall be as close as possible to the usual way<br>
>> (f.e. in astropy) -- which means: mainly no specific rules unless they<br>
>> really arise from the specifics of the standards development.<br>
>><br>
>> For the same reason, I would also suggest to use the basic git workflow<br>
>> with "master" as the main development branch, and to not the "gitflow".<br>
>> The latter is just more complicated and rarely used: among the >70 git<br>
>> repositories that I use for Debian packaging I almost none uses this<br>
>> way. And all they are well-maintained, with astropy being the largest,<br>
>> very lively and brilliant example. We should just follow astropy's<br>
>> practice unless there is a really proven reason why this doesn't work<br>
>> for us.<br>
>><br>
>> Best regards<br>
>><br>
>> Ole<br>
>><br>
>> On 13.11.19 13:58, laurent.michel at <a href="http://astro.unistra.fr" rel="noreferrer" target="_blank">astro.unistra.fr</a> (Laurent Michel)<br>
>> wrote:<br>
>>> Dear VO,<br>
>>><br>
>>> I'm starting to use the new GitHub framework for the VO standard elaboration.<br>
>>> My current experience concerns DataLink 1.1 which is still in design phase (before WD)<br>
>>> This project is quite active these days with ~5 contributors which provides an interesting experiment of our Github standard<br>
>>> process.<br>
>>><br>
>>> I would just give one personal feedback on the follow-up of the discussions we are having on Github.<br>
>>><br>
>>> Let's take an example of how things should work:<br>
>>> - The author A1 proposes to add the feature F to the proposal.<br>
>>> - A1 opens the issue proposing F.<br>
>>> - Another author A2 does not agree with adding F to the proposal<br>
>>> - The discussion continues on the ISSUES panel until a compromise is reached.<br>
>>> - Finally, A1 and A2 agree on adding F' in the text<br>
>>> - 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<br>
>>> relevance.<br>
>>><br>
>>> In the Datalink case, one PR has been open for some reason a little bit too early, therefore the discussion open on the ISSUE<br>
>>> continued on the PR thread. This has 2 bad consequences:<br>
>>> - Followers have now to check two places (ISSUES and PR)<br>
>>> - The discussion on the PR concerns the relevance of the PR itself.<br>
>>><br>
>>> This example shows the necessity of clearly separate both steps (ISSUE and PR):<br>
>>> - The ISSUE tool has to be used to discuss on *what* has to be add/remove/modify on the standard<br>
>>> - The PR panel has to be used to discuss *how* to do it (e.g. wording).<br>
>>> - The PR must not be open before an agreement has been found on the ISSUE.<br>
>>><br>
>>> This does not relate to some Github setup but to a few good usage rules that should be promoted somehow.<br>
>>> May some people with a better Git experience than mine share their feeling about this?<br>
>>><br>
> --<br>
> Mark Taylor Astronomical Programmer Physics, Bristol University, UK<br>
> <a href="mailto:m.b.taylor@bris.ac.uk" target="_blank">m.b.taylor@bris.ac.uk</a> +44-117-9288776 <a href="http://www.star.bris.ac.uk/~mbt/" rel="noreferrer" target="_blank">http://www.star.bris.ac.uk/~mbt/</a><br>
<br>
</blockquote></div></div>