First feedback on the GitHub usage

[Patrick Dowler]

Comments injected below to retain some context.

--
Patrick Dowler
Canadian Astronomy Data Centre
Victoria, BC, Canada


On Fri, 29 Nov 2019 at 09:45, François Bonnarel <
francois.bonnarel at astro.unistra.fr> wrote:

> I experimented recently proposing changes for DataLink-next using github.
> I found this technically more difficult than when we moved to volute.
>

I think feedback via mailing lists and wiki pages like DataLink_next still
have their place for the community to provide input (see below).

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.
>
Yeah, there is more tech and there is a learning curve to become reasonably
efficient at using github to collaborate.


> 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/
>
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  a
WG chair or vice chair doing "svn update" and "make" and
uoload-to-doc-repo...

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

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

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

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.

So, I'm not really positive about moving to github in these conditions.
>
>
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).

* shouldn't be too hard to push it to the WG wiki page, for example

Sincerely,

Pat


>
>
>
> 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/
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ivoa.net/pipermail/interop/attachments/20191202/4ce4dba6/attachment.html>