Minutes of discussion: Improvements to CF build & deployment processes

[erget]

Today a discussion took place on improving the CF build & deployment process. Participants:

• @DocOtak
• @dblodgett-usgs
• @ethanrd
• @erget
• @painter1

Overview of builds & repos

Some repos in the cf-convention gruop were deleted or archived.

3 repos are known to be active. This is now much more straightforward.

Conventions repo builds using Travis CI. Changes to master trigger a rebuild, and that gets committed to gh-pages, which are then in turn deployed as-is (nojekyll). This was described in a PR to the cf-conventions README by @dblodgett-usgs that has now been merged.

All participants are in info-mgmt team, and thus have admin rights to the relevant repos.

Note: We should be careful if renaming things to use the Jekyll redirect so that URLs don't break.

Way forward

• @ethanrd: We should consider building PRs or providing guidance on finding built PRs generated by GH Actions.
• @ethanrd: Investigate superfluous files / directories
• @ethanrd: Standard names built in website repo - this needs to be documented, probably XML gets exported from CEDA and pushed to GitHub. Allyson et al. will know more.
• @dblodgett-usgs: Document how Conventions get built and transported to webpage
• @erget: Refactor "rules" + CONTRIBUTING.md files
  • Migrate "rules" to a CONTRIBUTING.md
  • Separate to 2 docs: Contributing to Conventions (process model with GH annotations?), contributing to webpage
• Updating the Standard Names Table search tool - might be cool, but looks really scary 😢 Nobody wants to do that right now. @DocOtak will look at it, cautiously.

[ethanrd]

@erget - I'm not sure we should move the "rules" content into CONTRIBUTING.md. Is that what the 5th action item above means? I remember the discussion but don't remember a clear decision during the call. Or maybe I'm just waffling.

The website is the canonical reference for all things CF. So most new CF users will come to CF through the website not through GitHub. Given that, I think it makes sense to keep most CF documentation (except for the actual specification) on the website. (Except were it makes sense not to. Oops, waffling again.)

[DocOtak]

Looks like there is some prior discussion re the standard name search tool in #27. #7 is also potentially relevant.

[erget]

@ethanrd - I understand what you're saying, and yes, I remember the website vs. CONTRIBUTING.md thing being a component of our conversation. IIRC the thought was to try to combine them because they're intertwined, and somehow get them to appear in both places.

What I'd like to do for the moment is try to implement that and see if it works, and if it does, great - if not it'll be pretty obvious we need another approach.

[JonathanGregory]

Which document do you mean by the "rules"? Do you mean http://cfconventions.org/rules.html and http://cfconventions.org/errors.html? If so, I think they should stay on the website (not necessarily under the heading of "Governance") for maximum visibility (consistent with @ethanrd's remark). Of course they could be converted to markdown. Why not put CONTRIBUTING.md on the website too? The whole website is in GitHub anyway, as you know, so it's not really a choice between GitHub and web, just of repo in GitHub.

[JonathanGregory]

It would be helpful if @japamment and @davidhassell could consider this discussion, I suggest, since they are the secretaries of standard names and conventions, respectively.

[erget]

@JonathanGregory yes that is indeed my plan - I'm not sure if this is shared by anybody else at the moment but my thought would be to simplify those all into as few documents as possible. The main issue is that there are the rules for "contributing" to the CF Conventions, which are on the website (and could use some sprucing up IMHO), and the more technical rules for submitting pull requests and the like within the CF Conventions repository. These are 2 separate repositories, and both should have CONTRIBUTING.md files so that people find them readily.

I agree also that the current pages "rules" and "errors" should be discoverable via the website - if it's possible, I'd like to combine both of those into a single document, which would be CONTRIBUTING.md, and then redirect the old links to that one and rejiggle the hyperlinks that lead humans to the page. In short, a multi-stage approach but not overly complicated.

Once I've had time to do that I would be very grateful for everybody's input, including that of @japamment and @davidhassell .