search

cf-convention / cf-conventions

AsciiDoc Source
http://cfconventions.org/cf-conventions/cf-conventions
Creative Commons Zero v1.0 Universal
83 stars 43 forks source link

GitHub Contribution Guidelines #130

Closed dblodgett-usgs closed 5 years ago

dblodgett-usgs commented 6 years ago

Dear All,

As a next step toward the CF community using GitHub tools to discuss and refine the specification, we need contribution guidelines for this repository. For background and interesting reading, this issue follows #106 and #112 and is more or less governed by the CF community conversation in Trac ticket 160. The consensus in that ticket has lead us here.

The outcome of this issue should be an initial CONTRIBUTING.md and modifications to the pull request template per the requirements described below. We should use this issue to discuss and evolve these requirements then I will submit a pull request with content according to the consensus.

Please review the use case and guidelines below. I will begin work on the CONTRIBUTIONS.md document in a few weeks based on the consensus we have sometime in May.

Top level use case: As a contributor to the CF specification, I need to know the rules and instructions for how GitHub should be used, so I know the right way to submit my suggested addition or changes.

Guidelines: (derived from correspondence between @JonathanGregory, @dblodgett-usgs and others.)

Best,

Dave Blodgett

JonathanGregory commented 6 years ago

Thanks for starting this, Dave. I'm grateful to you for taking it on - it think it will be very useful. Since you've already included all my comments (!) I don't have any more to make just now. I hope others do. Jonathan

ChrisBarker-NOAA commented 6 years ago

Some thoughts:

Really great to get this out -- thanks for starting it!

Frankly, it's been a while since I've used TRAC much, but I think gitHub's Pull Request system provides some great opportunities to better manage changes to a document. IN the above, I see ideas like "Once agreed to in the issue, the change can be implemented and submitted as a pull request". But I think it makes more sense to go early with a PR. Often, the text itself what needs to be discussed -- so having the discussion directly in context of the suggested changes to the text has real benefits.

PRs support general discussion of the PR, as well as line-by-line comments specific text. This combination is ideal for many suggested changes to the doc.

So I suggest something like this:

Issues:

If there is a general issue about the standard that isn't specific to text, like "I suggest we support his new concept in CF" then that should be in an issue.

If someone notices and error, inconsistency, missing detail, etc, but does not have a suggested change to the text, that should be an issue.

Pull Requests:

In short -- go to a PR earlier rather than later -- as soon as someone has specific suggestions for changes to the text itself, that should go in a PR.

Any typo or minor correction should go straight to a PR.

PRs and issues can be pretty easily linked, so the transition is not bad -- if someone submits a PR that requires a larger discussion unlinked to any particular text -- it's not hard to start an issue and link to it. Similarly, if it starts as a issue, it's easy to link to a PR once one is created.

Potential Problems / Questions

Making it easy for newbies

Creating an issue is significantly less of a technical burden than a PR. That is, pretty much anyone with no experience with gitHub or text-based markup can probably figure out how to submit an issue. PRs, on the other hand, require more tech know-how -- gitHub makes it pretty easy to automatically create a fork for you if you try to edit a repo you don't have access to, but it's still a bigger lift to wrap your head around. So people should be encouraged to submit an issue if they have something to contribute (like correcting a typo, or...) that maybe should be a PR. A more experienced developer can make the PR later.

What do "core" contributors do?

People without write permissions to the repo need to create a fork to make a PR. But folks with write permissions to the repo have three choices:

1) make a change directly and push it. 2) make a branch, make the change in the branch, and submit a PR for the change 3) make a fork into their personal account, and make a change and PR from there.

I personally prefer (2) as a core contributor to projects.

(1) should only be used for the simplest of changes like typos, etc.

Some folks prefer (3) as a more robust way to control the process, but It makes more work, and we're all volunteers here, so we want it to be as easy as possible to improve the doc.

In particular, (2) makes it much easier for multiple people to work together on a change -- rather than making PRs against forks againsts forks....

Just my thoughts, having worked on multiple gitHub projects, some large, and some small, some as core contributor, some not.

graybeal commented 6 years ago

Thank you Dave!

Well captured Chris, I concur. (And even for people who are newbies this could be a nice gentle introduction to Pull Requests!)

I may be misremembering, but I thought that given the right configuration, text files in GitHub can actually be 'edited in line' and submitted as a pull request. (I do know that if you have enough privileges you can edit in line and have the results merged straightaway, but for sure that's not what we're doing in this case.) That could be a nice path to describe for people, if true.

dblodgett-usgs commented 6 years ago

Dear CF community,

I've started work on #130. It can be seen in pull request form between branches in my fork here or in rendered markdown form here

@ChrisBarker-NOAA -- I did not get all your ideas implemented. If you want to leave comments with proposed additional details or ideas for an additional section, I'm happy to copy/paste/rewrite, I just didn't really know how to fit your thoughts into the doc at the first pass.

Others, please don't hesitate to leave in-line comments on the pull request version, but please do also summarize your comments in line in this issue so they make it to the email list.

Note that I also added the Contributors Covenant as a placeholder for a code of conduct. Is there a pre-existing CF code of conduct written down some where?

@JonathanGregory -- do you want to act as moderator of this discussion? I think it would be in our interest to move it to near conclusion prior to the meeting in June.

Best regards,

Dave

p.s. apologies for the push of a couple commits to #115 that came over the email list a moment ago -- Those commits were promptly reverted and moved to another branch.

ChrisBarker-NOAA commented 6 years ago

@dblodgett-usgs wrote (in https://github.com/dblodgett-usgs/cf-conventions/pull/10/files):

""" My opinion is that Pull requests are really not a good format to evolve text like this. They are great for critiquing code and doing fairly tight reviews on style and syntax, but for long form review of text, they can be very problematic. """

My experience, like yours, is that PRs are great for small changes to text, fixing typos, syntax rewrites, etc.

And yes, not as good for long form review of text -- but I fail to see how an Issue is any better for long form review of text -- in fact, it's much worse -- and in particular, if you not adding a whole new couple pages, but rather one small section, to a doc (or a couple small sections that are related but in different parts of the doc), then you get as much context as you want, without an extra typing or management.

Now, for developing the first version of a largish doc with a small group, maybe Google docs is a better way to go, sure -- but I can't see how using Issues helps as all.

So again:

Once you are to the state of proposing a change to the text of the doc, whether it's a whole new section or a typo fix -- put it in a PR.

Also -- this is the first draft of the contributors doc -- whatever we do can be changed if things don't seem to be working as well as they might.

dblodgett-usgs commented 6 years ago

Dear Chris,

Thanks for humoring me and working through this in the main repository issue. I commented back inline in my PR between branches in my personal fork of the repository, but will leave a note here as well.

Why issues for discussion and PRs for syntax review? Partly because @JonathanGregory requested that:

A given proposal should be discussed as one issue. It shouldn't fork or be superseded by another one, unless that reflects what has happened to the proposal, in the same way that we continue discussion under one trac ticket for a given proposal. This is so that it's easy to trace the discussion which led to a given agreed proposal.

And because I totally agree. A proposal should be described as a problem or deficiency in the current spec (an issue). Then the solution planned and discussed among the community as one conversation that is traceable in one place. I think the issue interface is very well suited to this for it's markdown capabilities and integration with email notifications, among other things. The ability to link an issue to a commit and/or PR that resolves it is a very nice way to trace the connection between a problem, discussion of the fix, and the actual implementation of the fix.

Why a PR over in my personal fork and not here? Two reasons, 1) so people can opt into the early line by line review / not inundate the cf email list with PR review spam and 2) to demonstrate what the interface is like without implying that we use it whole-hog. Per Jonathan and my observations, the PR interface is really not suited to commenting on sentences and paragraphs of text. It breaks the text apart and can quickly get out of hand. Look at how commenting works in google docs and word, that is much better suited to editing written word.

I hope that in the future, we have a nice interface for diffing, commenting, and evolving text for this kind of application, but right now we just don't. So we need to kick out to google docs or fork repositories in small groups to evolve the text of major contributions and look to the future for better solutions.

Rereading your and my comments, I think we are largely in agreement. I have a few minor changes I'll check into my fork in a moment. Maybe you could take my "CONTRIBUTING" branch and evolve the text to better convey the imperfect but pragmatic position we find ourselves in?

Best,

JonathanGregory commented 6 years ago

Dear Dave

Thanks for your contributions. I could be moderator of this, and thank you for asking, but if David Hassell has time to do so that might be better since I'm rather short of time at present. Would you, David?

I agree with you that a googledoc is a good medium for editing large amounts of text (in the mode where edits are suggestions). Maybe some comments could be added about this possibility. There is a need to keep intermediate versions, I would say, as the issue proceeds to discuss them. If there is only one evolving doc it's not so easy to compare successive or alternative versions.

We should preserve the distinction between enhancements and defects that we currently have with the trac tickets. Perhaps pure typos could be identified as a separate category from these.

CF doesn't currently have a code of conduct but I agree it's a good idea to adopt one. That's a governance issue, I think. I wonder what Karl feels.

Best wishes

Jonathan

On Mon, May 21, 2018 at 12:35:43PM -0700, David Blodgett wrote:

Date: Mon, 21 May 2018 12:35:43 -0700 From: David Blodgett notifications@github.com To: cf-convention/cf-conventions cf-conventions@noreply.github.com Cc: JonathanGregory j.m.gregory@reading.ac.uk, Mention mention@noreply.github.com Subject: Re: [cf-convention/cf-conventions] GitHub Contribution Guidelines (#130)

Dear CF community,

I've started work on #130. It can be seen in pull request form between branches in my fork here or in rendered markdown form here

@ChrisBarker-NOAA -- I did not get all your ideas implemented. If you want to leave comments with proposed additional details or ideas for an additional section, I'm happy to copy/paste/rewrite, I just didn't really know how to fit your thoughts into the doc at the first pass.

Others, please don't hesitate to leave in-line comments on the pull request version, but please do also summarize your comments in line in this issue so they make it to the email list.

Note that I also added the Contributors Covenant as a placeholder for a code of conduct. Is there a pre-existing CF code of conduct written down some where?

@JonathanGregory -- do you want to act as moderator of this discussion? I think it would be in our interest to move it to near conclusion prior to the meeting in June.

Best regards,

Dave

p.s. apologies for the push of a couple commits to #115 that came over the email list a moment ago -- Those commits were promptly reverted and moved to another branch.

-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/cf-convention/cf-conventions/issues/130#issuecomment-390758888

davidhassell commented 6 years ago

I would be very happy to act as moderator, if that OK with you, Dave?

Adding a label to an issue is easy and should go into the guidelines.

I agree with what has been said about googledocs, but we should remember that they are not, at present, universally accessible and so we should always have alternatives.

David

ChrisBarker-NOAA commented 6 years ago

I agree with what has been said about googledocs, but we should remember that they are not, at present, universally accessible and so we should always have alternatives.

A google doc is also essentially ephemeral— it is not a good place to record history, or the ability to roll back changes, etc.

We should use git+gitHub for what it is good for.

Granted, these are tools designed for code, not text documents, but when you are working with a plain text markup language, they really do work well.

In fact, being able to use them with a version control system is one of the primary motivations to using text-based markup.

The CF standard is a pretty mature document. Most of the changes will be small, and well suited to the “diff” based approach of gitHub.

So we should use gitHub for those changes.

Occasionally we may have a large new feature ( like the recent geometries one ). If the primary authors of such a section find it more productive to develop the first draft in google docs (or whatever they want), fine. But it should go into a PR once there is a draft proposal.

-CHB

ChrisBarker-NOAA commented 6 years ago

@dblodgett-usgs wrote:

I hope that in the future, we have a nice interface for diffing, commenting, and evolving text for this kind of application, but right now we just don't. So we need to kick out to google docs or fork repositories in small groups to evolve the text of major contributions and look to the future for better solutions.

Frankly, gitHub PRs are a pretty darn good interface for "diffing, commenting, and evolving text" it does fall down a bit on a having a good way to comment on an existing doc, rather than just the diff, but not too bad.

"kick out to google docs" (or anything else) is a bad idea -- the whole point of git is to preserve the history, that's the part we really want to keep.

However, key is that we need to start with a policy, and then see how it goes -- frankly, we can't nail down an exact policy anyway, and people wouldn't exactly follow it if we did.

But in short, my suggestion is:

dblodgett-usgs commented 6 years ago

Dear all,

Apologies for going mute for a bit. Apparently, my email overlords (bow to the security gods) decided that github notifications are spam -- amazing how you don't miss notifications when they are gone.

I 100% agree that an external document is an imperfect solution that is really only suited to pre-community-review draft development.

I also agree that we should have issue "labels" to enhancement, defect, and typo. I will add a note that labels should be used if at all possible to the guidelines.

Yes, @davidhassell -- sounds great to have you moderate.

erget commented 6 years ago

I agree with the discussion wholeheartedly, which for the sake of keeping things tidy and confirming my own understanding I summarize as follows:

Perhaps more refinement is possible - we discussed at the meeting having some kind of a beta version of a next release for a time. This would be compatible with this workflow (which is one of many possible ones, but fairly simple and IMHO straightforward).

cameronsmith1 commented 6 years ago

This seems reasonable to me. I would expect that some active management may be needed in the run-up to a new release, ie managing which PRs get merged or held until after the release. However, that shouldn't affect your general outline.

ghost commented 6 years ago

I propose something inspired by Git Flow, roughly as follows: master is the current release. next is the next release, an "editor's draft", if you will.

I don't think we need a next branch. Each new convention version will be a tagged release in the master branch thus allowing this branch to represent the Editor's Draft. All the new material merged into the master branch after the last release is assumed to be accepted for the next release, barring any stylistic or formatting changes.

The process would go something like this:

  1. Anyone who wants to propose a change to the convention should fork this repository. (I assume the number of those with commit privileges will be small so forking is what majority will have to do.)

  2. Create a branch off the master in the forked repository and work on the proposed changes in this new branch.

  3. Creating a pull request to the upstream (the official convention's) repository initiates the formal review process of the proposed changes.

  4. Pull request creator is responsible for updating its branch and the text of the changes with the upstream's master branch during the review process.

  5. The review process ends when the pull request branch is merged into the upstream's master branch.

It would be good to appoint, at least nominally, a few editors for every new convention release. They would be in charge of preparing the text in the master branch for the next release and making sure the review process of any open pull request is reasonably timely.

dblodgett-usgs commented 6 years ago

I 💯% agree with @ajelenak-thg.

I think this is more or less how the repository works now and this is a very natural pattern. Released tags would get built and stored as binaries here: https://github.com/cf-convention/cf-conventions/releases as well as on the main cf web page.

erget commented 6 years ago

This is definitely the most natural way to work on GitHub and very git-native, which I like. However, I do think there is merit in having a next branch. Because CF isn't software that we're releasing with continuous delivery, having fewer, but larger, changes between versions is probably the better way to go. It also better reflects the understanding achieved at the meeting - namely, that master is basically a release branch, and that the draft (whether named next or something else) collects changes before merging them all into master.

Concerning the workflow @ajelenak-thg outlines - that's certainly the way I intend to work, but my feeling is that we'll perhaps need to have a bit of patience with people who are new to both git and GitHub as they get used to it, so we shouldn't be too strict with enforcing the specifics of that workflow.

So the only point of ambiguity for me is the branches. I do think that having master only be merges with tagged releases has advantages for novices - even though you can achieve the same amount of traceability by only tagging releases, and declaring intermediate commits on master as transitionary, I think that having non-tagged releases appear as the repo's landing page could be confusing to some of our contributors.

marqh commented 6 years ago

I think that the people who are new to github will appreciate a lack of complication in the structure of information and how to engage.

Having a single branch makes is clear to anyone arriving that if they want to propose a change, that is what their change is with respect to.

So, I am in favour of maintaining the master as the editor's draft and providing tags for released versions and against a next branch.

I have also proposed a change to the CF website that makes the current state a little more clear: https://github.com/cf-convention/cf-convention.github.io/pull/61

ChrisBarker-NOAA commented 6 years ago

I agree with @ajelenak-thg and @marqh here -- I don't see a utility in having a next branch.

In general, master is supposed to be the "lastest" version, not ready for release yet.

As for "CF isn't software that we're releasing with continuous delivery, having fewer, but larger, changes between versions is probably the better way to go."

I'm not sure that it makes much difference how many changes there are between versions. Also -- maybe we should move to a more continuous delivery model -- why not have more frequent point releases that have clarifications and typos corrected?

What we should do is be sure to crate a branch for significant changes or additions, then they can be fully developed in that branch until ready for merging into master.

erget commented 6 years ago

I don't feel strongly about how we do branches and since I'm the only one currently supporting having a next branch on here that's fine with me. I think the release frequency is something which should be discussed more widely, but it's independent of our workflow for producing releases.

davidhassell commented 6 years ago

I think that we have to be very clear this is a proposal for how github issues can replace Trac tickets (as opposed to anything else we currently use, like the mailing list) and, at the this time at least, nothing else. This issue is concerned with how best to use github to carry this out in a way that make sense to people now, and in 20 years time.

In particular, github issues are only for completely defined proposals, not for any sort of speculative change; and all proposals must be raised as an issue (although that could coincide with a pull request for simple cases, e.g. typos).

The discussion has widened a bit to include "how should we integrate accepted proposals into CF", which is fine, but this is a separate concern to the original "how should we get a proposal accepted". These two are certainly connected, but will need quite distinct guidelines.

The original proposal contains guidelines that I think say

  1. Start by using a github issue just as you would a Trac ticket
  2. ...
  3. When it is finished there will be a pull request

How we get from 1. to 3. is less clear to me, but that will be resolved by the discussions in this issue.

When I come back in 2038, I need to be able to start at the top of #130 and be able to follow the arguments that led to its conclusion. Linking out to pull requests as part of this read through is fine by me, although I have a concern about searching - if I search for "foobar" in the issue, will it also search for that string in all referenced pull requests? This was also an issue for documents attached to/linked form Trac tickets, but the reality was that they were very rarely used, and if they were it was not for essential items such as proposed text changes.

JonathanGregory commented 6 years ago

Dear all

As David H says, I think we should first decide the procedure for making decisions on changes using GitHub (as an alternative to Trac). This will be part of a modified version of http://cfconventions.org/rules.html, so at this point we need explicit text to put in that document. In principle it should be the same procedure as now regarding the time-limits etc.

One change in the procedure could be to recognise an extra kind of change request i.e. typo, which is different from defect or enhancement. A defect is a proposal to change the words of the document to correct an error or clarify them, with materially changing the meaning of it. Someone else might disagree with the proposer of a defect ticket and think what they propose is actually a material change to the meaning, and in that case the proposal has to be discussed as an enhancement instead i.e. not accepted by default. A typo is an even more minor change which fixes something that seems evidently to be simply a mistake. However it's possible, in an analogous way, that someone else might say that it's not a typo, but deliberate, in which case it'd have to be discussed as a defect or enhancement instead.

I think that a typo could be proposed with a pull request, but a defect or an enhancement should be started with an issue, as David H says, and proceed to a pull request when it's fairly well agreed and it comes to a matter of wording.

Cheers

Jonathan

davidhassell commented 6 years ago

I have a concern with the hybrid github/trac approach: Some github issue numbers are/will be the same as Trac ticket numbers.

Is this managable?

David

ghost commented 6 years ago

It is manageable only with additional context, for example: Trac #101 or GH #101.

Alternatively, GitHub's API can be used to create and close dummy issues until the internal numbering is bumped up above the highest ticket number on Trac. Or go all the way to, say, 200. So all ticket numbers below 200 belong to Trac; above 200 to GitHub.

ChrisBarker-NOAA commented 6 years ago

So all ticket numbers below 200 belong to Trac; above 200 to GitHub.

+1

sebvi commented 6 years ago

why not simply import all past TRAC tickets and convert them into github issues? I am sure we can find that kind of scripts, possibly in a github repo!

sebvi commented 6 years ago

1mn googling: https://github.com/mavam/trac-hub

dblodgett-usgs commented 6 years ago

Dear All,

I would be supportive of a clean break from Trac -- and it's clear that there is a constituency in the community that would prefer that path. I think it is also clear that we are suggesting that outcome in the near future anyways, but potentially not an immediate retirement of Trac. While it may introduce a bit of confusion, my opinion is that confusion may be worth while to keep all community members engaged and be as inclusive as possible. At the end of the day, those of us that prefer using github need to demonstrate how to evolve the standard in github so those without experience in this environment can learn and join the :shipit: tribe. (I use the squirrel as an example of how foreign some github traditions and mechanisms really are.)

Is there any strong disagreement to this line of argument? My thinking is that we would continue to allow use of Trac until usage has dropped to near nill or maintenance of Trac is not worth the effort. Putting a timeline on this may not be worth the energy as it should happen naturally if this switch to github really is the thing to do.

I also think it would be a great idea to migrate the Trac history to a block of github issues. While the numbering would reset, we could embed the original Trac URLs in the issues for continuity. I think this would naturally occur at the time that we retire our use of Trac.

Best,

Dave

p.s. I would like to remind everyone that while we have moved some of our discourse to github, I think we should attempt to maintain the traditions of CF in our correspondence. Each of these comments fires off an email to the group and, as such, should be thoughtful and worthy of people's attention if at all possible.

davidhassell commented 6 years ago

OK - I prefer the second option, because I can see the prefix getting dropped somewhere down the line, and the format isn't really part of the proposal.

Most of the existing github issues record the process of creating 1.7 from the backlog of concluded tickets in Trac. The github issues seem like the natural place for these things and, for example, the recent ticket on an asciidoc issue (#135).

Perhaps we need a new, seperate repository for change proposal e.g. cf-convention/change-proposals (or some such name). Then we can keep issues in each of the separate repos (cf-conventions, Conformance, cf-convention.github.io for all the other practical (rather than scientific or logical) thing that crop up.

Do pull requests work across repos in the same project?

Thanks, David

taylor13 commented 6 years ago

Hi all, I am told that PCMDI's maintenance of the Trac site here at LLNL is becoming more fragile for a number of technical reasons and our scarce resources to invest in it also make it problematic, so from a practical perspective our systems folks here would favor moving to github (although it is not imperative that this happen immediately).

Like others I am concerned about consistency of and/or conflicts between issue numbers associated with the Trac and github discussions. If we renumber the trac issues won't it disrupt the cross-referencing already in those discussions? Karl

dblodgett-usgs commented 6 years ago

@davidhassell

I think there may be some logic to creating a new repository that is dedicated to change proposals and community governance. That way people could "watch" that channel for topical conversation rather than syntactical review that needs to happen on the asciidoc. Anyone else want to chime in on this proposal? If we decide to go down that road, I will need to rework much of the content I've been working on for this, but that's all good -- just want to bring this to some form of conclusion.

Regarding integration of pull requests across repositories, look up in this thread a bit. You'll see a link from https://github.com/cf-convention/cf-convention.github.io/pull/62 that got put there when I linked to this issue from an issue in: https://github.com/cf-convention/cf-convention.github.io

Best, Dave

erget commented 6 years ago

I think there could be some benefits for this, but yes, we'd need to update the contribution guidelines to be really clear. Perhaps the easiest thing to do would be to clone the cf-conventions repo and rename that so that topical pull requests / discussions go there, and then once things have been integrated on that side pull them across to e.g. this repo, which would be used for releases, including syntactical / editorial changes in order to keep the adocs up to date. As @dblodgett-usgs notes this would be easier for users wanting to only be involved in the content-related discussions.

For me this seems overly complex, but if the community really wants to be able to restrict spamming it could be a good way to go. Personally, I think the better alternative would be to post to different lists based on issue tags - I've heard of Hubot integrations which allow this, for example.

In that vein, I'd also be in favour of moving the Conformance into this repo, because that would make the workflow easier for ensuring that both the Conventions are updated simultaneously (I'm thinking of PR checks, as an example).

rhattersley commented 6 years ago

As a general observation on the transition from Trac to Github, I would encourage embracing existing GitHub idioms to take advantage of the resulting simplicity. For example:

re: porting Trac issues to GitHub, I would recommend that you copy them to a separate repo dedicated to being an archive. That way the issue numbers can easily be preserved. If there's a need for new native GitHub issues to refer back to the Trac content, cross-repo links are still very easy, e.g. cf-convention/test-trac-convert#1.

re: conversations on "practical" vs "science" topis, I would recommend keeping all your issues and pull requests in the repo that they affect. Workflows across multiple repos are more complicated and error prone, and much less likely to receive any attention from GitHub. @erget's suggestion to take advantage of issue labels is a more natural fit. The use of issue labels is very common on GitHub.

JonathanGregory commented 6 years ago

Dear all

I agree with @rhattersley that it would make sense to copy the trac tickets to a separate cf-conventions GitHub repository, with their original numbers, in order to keep them for posterity. I don't think we should oblige everyone to switch immediately to GitHub and stop using Trac, though we can encourage it. The meeting last week was certainly in favour of a quick move, but the people at that meeting may not be an entirely representive sample of the whole community of contributors to CF. I guess it was a more technically minded set than the average.

We currently have three main repositories: the website, the conventions and the conformance document. I suggest that, for simplicity and unless it becomes inadequate, we could deal with governance issues in the website repository, because the gobernance rules are part of the website. This ticket ought to be in that repository, not this one, if you agree with this idea. I agree with @erget that it would make sense to merge the conformance and conventions repositories, since they have to be updated together. The data model will also belong with them.

I don't know how the mechanism works for sending these postings on issue to the CF email list. If this system can filter by label, we could follow what @erget and @rhattersley suggest to mark some of them as not to be distributed.

Best wishes

Jonathan

ChrisBarker-NOAA commented 6 years ago

On Thu, Jun 28, 2018 at 5:50 AM, JonathanGregory notifications@github.com wrote:

I agree with @rhattersley https://github.com/rhattersley that it would make sense to copy the trac tickets to a separate cf-conventions GitHub repository, with their original numbers, in order to keep them for posterity.

+1

I don't think we should oblige everyone to switch immediately to GitHub and stop using Trac, though we can encourage it.

yes, we should -- having the same thing managed two ways is a pain in teh

^$*.

I know change can be hard, but semi-change / lack of clarity, confusing mess is harder.

And it's really not that different for the common use cases!

The meeting last week was certainly in favor of a quick move, but the people at that meeting may not be an entirely representative sample of the whole community of contributors to CF. I guess it was a more technically minded set than the average.

maybe so -- but TRAC isn't exactly a model of usability :-) gitHub (at least for issue management) isn't any more technical that TRAC, and I think it's more usable, not less. So it's more a old dog / new tricks issue.

-CHB

--

Christopher Barker, Ph.D. Oceanographer

Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov

davidhassell commented 6 years ago

A summary of where I think we are:

There seems to be a consensus for:

I think that some more discussion is required for (perhaps some of these questions are nearly agreed):

I'm assuming that the discussion on how/when to merge completed proposals will be carried on in a different discussion, so we can move the original proposal of #130 to a faster conclusion.

Thanks, David

dblodgett-usgs commented 6 years ago

I agree.

On the outstanding issues:

  1. Trac in parallel? I think we are already in a phase where it is being used in parallel. The goal should be to shut it down, but as I've argued in the past, it may be too much to require a sharp transition.
  2. I really think we should try using one repository and the email list. The cleanest solution would seem to be to migrate trac tickets to a new repository and bring the git commit history from https://github.com/cf-convention/cf-conventions into it. From that point forward, https://github.com/cf-convention/cf-conventions would be deprecated and all new work would take place in the new repository. I think that naming shouldn't be a problem. The new repo could be cf-convention or cfconventions or maybe we could just swap the names?
  3. I would like to suggest that the conformance document be a separate issue all together.
erget commented 6 years ago

Dave,

  1. Agreed, I don't see a reason to rush this.
  2. I think this approach would actually be more confusing, what would be the benefit of making a new repository? Also, what about links pointing to the current one? Lots of questions arise. Migrating is straightforward, yes, but managing the consequences is not necessarily and for me at least the benefit isn't clear yet.
  3. I may not be understanding you completely. Would you place the conformance document outside the scope of the Trac vs. Github migration (I would agree with this wholeheartedly) or are you advocating for keeping the conformance document outside this repository in the course of the Trac vs. Github migration (I would desire further discussion if this were the case)?
dblodgett-usgs commented 6 years ago

@erget

The benefit of making a new repository would be the ability to migrate trac history 1:1 preserving issue numbers. I don't feel strongly about this at the end of the day though. My only strong opinion is that we not split discussion into a repository for discussion only. I think we should try to keep it as tight as we can.

Yes, I think the conformance document should be treated as a separate discussion from the Trac to Github migration. Clearly related, but not enough to muddy this discussion with that.

Best -- Dave

davidhassell commented 6 years ago

Where I think we are on the outstanding questions:

Thanks, David

graybeal commented 6 years ago

These days I am not a heavy user, so please discount these observations as you see fit.

If I am not mistaken, David H's bullet 1 is affected by bullet 2. Namely, if you are going to copy from Trac to GitHub, and if wherever that copy gets made is used to continue discussions on those points, then all Trac activities cease as of the change-over day, to be replaced by GitHub. Which I think would be most time- and cost-effective.

This next may sound radical but as a practical matter, if it is only 174 tickets, this need not be a huge deal. If there are people spending 50% of their time reading Trac tickets, then maybe it needs to be done just right. But for 174 tickets, many of them closed, I think even if you don't make the numbers track with trac (sorry), the total number of impacts is going to be small on day 1, and vanishingly small after a year. OK, 2 years.

1) Step one is copying the tickets. As mentioned, there are at least 4 GitHub projects and this Slack page lists a number of approaches, some of which look quite mature: https://stackoverflow.com/questions/6671584/how-to-export-trac-to-github-issues. Copy the tickets at the end of the current repository (existing ticket #$), making sure Trac's closed tickets are closed in GitHub. (I'm not sure you'll be able to save the dates of all the entries with these tools; but if it's easy, you could copy the dates as the first line of each entry/comment. Copying the original Trac # wouldn't hurt either.) 1A) If you absolutely had to clean up all those links, somewhere in the transition pipeline write a script to convert all the links in those 174 tickets to point to the new GitHub ticket/comment location, if that isn't handled automagically by the conversion tool. But see comments at end. 2) Either manually or via a script, create an entry for the last comment of each existing Trac ticket that says "Discussion and maintenance of this issue has been moved to ."
3) If you feel compelled to have a forward reference after the Trac repository goes entirely away, use a separate repository to copy the 174 tickets (preserving the ticket number) with just the title of the ticket, and an entry that says the same thing as above. Or create a ticket-mapping entry.
But if you count the number of open Trac tickets, the number of comments being actively made on them, the number of people making them, and the number of cross references those people need to follow, I propose it is not going to be a major crisis for everyone to adjust to the new location in the new repository, especially given the titles are the same and the previous Trac (or a copy of it) has a forward lookup/reference.

I don't think the fact that all of this could change again someday is an argument that says the new numbers have to match the old. Either way all the numbers/references might have to change again.

It would definitely be ideal if numbers were unique and matched; but even if some were duplicated and they didn't match, you will always be able to manually recognize that for all the new github tickets that came from trac (from #$+1 to #$+174 in the github repository), the internal Trac numbers (1-174) will need to be mentally cross-referenced into the new Github numbers (original number plus #$). This could be done automatically at the time of the next conversion, if it isn't done this time around, or even manually as desired on a per ticket and per comment basis.

cf-metadata-list commented 6 years ago

Dear David

I agree with your proposals to stop new trac tickets quite soon and to put the conformance doc in the same git repository as the conventions doc.

Earlier and at the CF meeting last month I argued in favour of continuing with trac for the moment, because I think it's important that potential contributors to the conventions are not deterred from contributing. There are some to whom the use of GitHub may seem a formidable barrier. (We know that there are others who find that surprising, because they are familiar with GitHub and regard trac as impenetrable. This legitimate difference of views reflects people's ways of thinking and experience, I expect.) To help people start using GitHub, we will have the guidelines, whose development Dave has been leading.

This is now the time and opportunity for anyone in the CF community to say if they are concerned about the prospect of being required to use GitHub in the near future to make proposals for changes to the conventions. (The use of the email list for discussion and standard name proposals will continue.)

Best wishes

Jonathan

On Fri, Jul 13, 2018 at 12:50:21AM -0700, David Hassell wrote:

Date: Fri, 13 Jul 2018 00:50:21 -0700 From: David Hassell notifications@github.com To: cf-convention/cf-conventions cf-conventions@noreply.github.com Cc: Subscribed subscribed@noreply.github.com Subject: Re: [cf-convention/cf-conventions] GitHub Contribution Guidelines (#130)

Where I think we are on the outstanding questions:

  • whether or not to run Trac in parallel for a while

    I suggest that, for new proposals, we do not run Trac and gihub for new proposal parallel. In practice this would mean:

    1) We would set a date (that would presumably coincide with the acceptance of this ticket) after which new proposals must be made on github and no new proposals will be allowed on Trac. Discussions can continue on Trac until ... 2) We set another, later date, after which Trac will be turned off and its content archived. Any unfinished Trac discussions will be effectively closed. If there is still a will to continue a discussion then the proposal must be raised anew as a github issue proposal. (This is not as extreme as it first sounded to me - there are Trac tickets that have been open but haven't been posted to for over 10 years - these were never going to be resolved before Trac is turned off!)

  • whether or not to create new github issues in the cf-conventions repo, the same repo as the copied Trac tickets, or yet another repo. [Whatever the answer, labels will be in use to help discern issues.]

    It seems that there is support for copying the existing Trac tickets to a new "archive" repository; but raising new proposals in the existing cf-conventions repository. New proposals can happily coexist with other issues (such as "should we use italics for example captions?") with the use of labels.

    We would "fast-forward" the issue numbers in the cf-conventions repo so that new proposals would have different numbers to old ones - currently that means creating dummy issues up to and including nunber 174. This is important because if we didn't do this then our issue referencing could break in the future if we were to alter our change procedure yet again (such as if github were to ever fail to meet our needs).

  • whether or not to move the conformance document to the cf-conventions repo

    There is a compelling reason for moving the conformance document to the cf-conventions repository in that then there would only ever need to be one pull request per completed proposal. In the current situation (i.e. conformance in its own repo), some proposals will need two pull requests.

Thanks, David

-- You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub: https://github.com/cf-convention/cf-conventions/issues/130#issuecomment-404755429

neumannd commented 6 years ago

One minor comment on whether to run Trac and GitHub tickets in parallel or not: Most of us are registered at various web services and need to remember/save the login details for these services. Using Trac and GitHub in parallel for a long time period means for us to have two logins detail sets for cf-conventions tickets. One login set more or less isn't much -- but it sums up. Also we need to remember/save/bookmark two URLs for ticket system. Therefore, I would prefer a short transition phase. But that's my personal opinion.

dblodgett-usgs commented 6 years ago

Hi All,

This conversation has come quite a long ways. Glad to see that we are coming to some conclusions.

I've done a bit of cleanup on the "CONTRIBUTING.md" document in the pull request mentioned above. Please comment and edit away.

If we can work that text to finality, I think we just need to pick the timing of the switch over and put together the task list to get us there. Lots of food for thought about a task list above.

Best,

Dave

erget commented 6 years ago

One thing we might wish to include in the contribution guidelines would be the branch which contributors should contribute to. As it is we say they should create an issue and a pull request which matches that issue, but there are some branch management issues which would have minor effects on this. If we have a branch for the next version of the convention, say 1.8, should everybody base their branches off of there? Otherwise, if they're always branching off of master, there's the possibility that they'll fiddle with areas which will produce conflicts later, e.g. the author list or the version number.

Alternatively, we could say that the files which contain such common metadata related to the convention itself shouldn't be edited in a topical PR, but rather only be changed editorially in preparation for publishing a new version.

dblodgett-usgs commented 6 years ago

According to the discussion above, I think we've agreed that developments beyond the most recent tagged and deployed version would take place on master.

I 100% agree that we should consider updating "history" and other common metadata as you say when we cut a release to avoid merge conflicts. I'll add something to this affect unless there is objection?

JonathanGregory commented 6 years ago

Dear Dave

Thanks very much for moving this forward. I think it's almost there. When agreed, this will be a change to the governance rules on the website, so it really belongs in that repository, but never mind!

Best wishes

Jonathan

dblodgett-usgs commented 6 years ago

Dear Jonathan,

Actually, this text will end up in a "CONTRIBUTING.md" in this repository. It may also end up on the main web site. This pull request likely needs some attention in light of the conversation here.

I will get these changes checked in soon.

Best,

dblodgett-usgs commented 6 years ago

Dear All,

I got the changes noted in my previous comment implemented.

I've also updated the rules to reflect our switch to github only. Some cross linking of the github CONTRIBUTING.md and the rules are in order?

So what are our next steps? It seems we have come to a basic consensus and should pursue a role out of this strategy?

Best, - Dave

JonathanGregory commented 6 years ago

Dear Dave

I think you've done an very good job of this. Thanks a lot. I have a couple more points:

David is moderating this discussion, I believe. If we're following the usual rules, he should summarise the state of the discussion, and if no-one says anything more for three weeks, it's a done deal. However, David is on holiday this week, and I think next week. Sorry about that.

Best wishes

Jonathan

dblodgett-usgs commented 6 years ago

Dear Jonathan,

I've updated https://github.com/cf-convention/cf-convention.github.io/pull/62 to include changes to errors.md.

I opened https://github.com/cf-convention/cf-conventions/issues/131 to deal with labels. My suggested changes are:
Remove: asciidoctor mod?, bug, invalid, simple. Add: typo, style

OK, I'll wait for @davidhassell to summarize.