search

martinthomson / i-d-template

A template for IETF internet draft git repositories
Other
208 stars 182 forks source link

Canonical CONTRIBUTING.md #310

Closed larseggert closed 2 years ago

larseggert commented 3 years ago

The IESG is at the moment discussing what to do with https://github.com/ietf/repo-files. It was supposed to hold Markdown versions of various boilerplate documents for easy use in IETF repos.

In reality though, many/most IETF repos get their boilerplate from your i-d-template (and the template-template.) Would you consider using something provided by the IETF org instead? I'd be happy to give you write access to that repo, so you could make changes as easily as in your own.

(This is mostly about CONTRIBUTING.md. I am asking the Trust to make a canonical LICENSE.md available, and the IETF ops people to make a canonical Note-Well.md available. They would either live in that same repo, or elsewhere, where they can be kept synchronized as changes are made to the various web versions which are at the moment canonical.)

martinthomson commented 3 years ago

My goal here is not to have to maintain those files, so whatever we can do to have these files maintained centrally makes sense.

The balance here always needs to be between meeting our obligations with respect to notices against making the files usable for new contributors. The CONTRIBUTING.md here includes some boilerplate that was originally provided by the IESG (or maybe the IETF Trust, or maybe the IETF counsel, I don't exactly remember which). I can try to recover the history there if that helps.

I've also added some contextual information that is aimed at helping new contributors find their way. Some of that is specific to the use of this repository (like the use of mailing list links and {WG_NAME} placeholders).

If there is something we can do to ensure that the obligatory portion of these files is consistent, that is probably a good idea. For instance, we could automate a check that ensured that that portion matches the official versions. That way, there would be a single source of truth for what the notices should be (presumably with some process around its maintenance), with copies that are validated automatically.

Regarding a note-well file, I'm not convinced of the utility of that. Do we really want out-of-date copies of the note well floating around? If there is a link we can provide, then that is better (that is the approach originally taken). That applies generally. For instance, I would be happy to reference a license, if that weren't somehow not permitted under certain legal constraints.

larseggert commented 3 years ago

OK, I'll let you know when I hear back from the Trust about a canonical LICENSE.md. FOr CONTRIBUTING.md we could take what you have now as the starting point and then edit it as needed.

I was thinking to remove the Note-Well.md from the current repo; I have asked the IETF secretariat if they could publish a Markdown version themselves, and keep it in sync with any changes made to the web version, which I think they consider the canonical version.

larseggert commented 2 years ago

I changed track on this and added a GitHub action that automatically pulls the license and note-well, fixes some nits, and markdownifies them. When a change to what's in the repo is detected, the runner opens a PR.

Since CONTRIBUTING.md is pretty dependent on the audience, I decided to not offer a template at https://github.com/ietf/repo-files and instead just link to examples.

So you could pull LICENSE.md from https://raw.githubusercontent.com/ietf/repo-files/main/LICENSE.md going forward...

martinthomson commented 2 years ago

Closing in favour of #328.