Guidance request for new opensource repos - fork, or generate, from this repo?

[ajnelson-nist]

I did not see a reference on expected or requested practice for this repository in its README or the linked Quickstart Guide.

This repository is capable of evolving, especially w.r.t. its embedded taxonomy and any "Upstream" policy updates from NIST. If I use this repository as a generative template to start another repository, I do not think there is a reasonable way, aside from timestamp, to determine what has changed to the template since I started.

I could work around this instead by "Forking" this repository. If I start at its current main state, starting "My" code base by modifying things and making a commit, I can then review later changes to the template by comparing Git histories.

The upsides to the "Forking" strategy are at least: I get to use Git tools to port updates; and I get to review my code bases for having a shared history with opensource-repo, in order to see if there are any templated things I need to update. Further, I can see the last time I synchronized my repository with opensource-repo, with git merge-base.

The ...not necessarily downside, but possibly oddside...is every contributor to this repository becomes a contributor to the forked repositories.

Can the README please be updated with guidance on how to use this template?

I'd also be happy to hear if this whole Issue is moot by merit of some backend template magic that notifies template users of upstream updates. I'm not aware if that's already provided somehow.

[wd15]

Hi @ajnelson-nist: I don't think forking is a good idea for the reasons that you raise. This repository will keep evolving no doubt. In my view it's a guide, nothing more. Currently, it's only asking NIST users to have a CODEOWNDERS and CODEMETA.yaml (they most likely already have a license and a README.md) so I'm not even sure using this as a template is really necessary. I certainly wouldn't if I was initiating a new repository. I would just add those two files and update them as best I can and then forgot about it.

I think that the correct answer is to have a NIST bot that checks repositories and warns owners via issue and/or submits an automated PR with the necessary files if they're missing with as much data automated as possible. Repository owners may have to modify the PR if necessary with correct meta data in cases that can't be inferred. Expecting people to remember to update meta files based on some standard that keeps changing is not a viable option as you point out.

Regarding the README. It looks fairly clear to me. It's asking users to include the four meta files. Maybe just mention to ensure these files are needed more explicitly and possibly say using as a template is an option, but forking is a bad idea?

[ajnelson-nist]

Thanks, @wd15 . I'm fine with a remark discouraging forking being included.

[tkphd]

Ah, good point. The recommended practice is clicking the shiny green "Use This Template" button: this is like a fork, but without the upstream connection, since the "derived" repositories are expected to quickly diverge and never sync back up.

Clarifying this in README means introducing a clause that will make no sense in the derived repositories; we can add another clause in the section on adapting this for your open-source work.

[tkphd]

Template users are not notified of updates: the assumption is that a clean break will be made. LICENSE is not expected to change much; even if/when it does, existing statements remain compliant. While template users can periodically wget LICENSE.md from here, it's not necessary.

Updates to CODEMETA are trickier and more likely to break things. Propagation would probably involve a manual process of finding repositories with the outdated file and contacting the CODEOWNERS to request changes (adding, removing, renaming, ...). I think this will be rare, and for the reasons you mentioned (esp. contributor lists), it's better to separate the "real" repositories from the template.