Synchronize Documentation: Synchronize documentation versions in template repos

[jpl-jengelke]

Checked for duplicates

Yes - I've already checked

Category

Information Sharing - documentation design, templates, communication, etc.

Describe the need

We have a need to ensure that documentation files are canonical and updated regularly in templatized repos. For example, the README format is updated in the slim-starterkit repository but it is not updated in the slim-starterkit-python repository. Similar scenarios evolve with GitHub PR and Issue templates, GitHub Action YAML descriptors and other files.

This proposal is to script the copy and release of approved changes. The slim-starterkit repository will be declared the canonical reference. All requested files will be copied into the other repos distributing these files and a PR created. The PR will be automatically approved and the repo will also be automatically tagged. All updated files will be distributed by a single execution.

Potential files:

• CHANGELOG.md
• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• GOVERNANCE.md
• LICENSE
• README.md
• others, as determined

Versioning: Version numbers will be inserted at the bottom of all files, according to the last known tag version of the slim-starterkit repo. The script will only execute against the main branch so as to only collect tagged content.

Technology: The script may be Bash-based or through the multi-gitter tool.

[riverma]

Hi @jpl-jengelke - thanks for this ticket. I have some thoughts:

• I’m not so sure about making slim-starterkit the “canonical” version of all files. Not all SLIM deliverables will be applicable within the slim-starterkit repo, so I think we’ll have to keep in mind that the slim repo will have to be the authority for certain items. For example, written guides, non-GitHub related automation, etc.
• Adding version numbers to version controlled files (that have hashed versions already) may be overkill. We should be able to use Git hashes for version control from GitHub metadata.
• An automated solution sounds good but might be a bit complex to write and maintain.

Based on the above, I’m wondering if we can we investigate the option of ensuring the maintainers of the slim-starterkit have notifications set-up to be informed when the slim repo makes an updated merge of artifacts and for the maintainers to manually update repos like slim-starterkit and slim-starterkit-python, etc.? We might be able to use Dependabot dependency updates for this type of update. The reason I suggest this is that I’m unaware of major software projects that automatically update dependency references by version without a human in the loop. We might want to keep this process manual to ensure the integrity of the starterkit repos. For example, if we have multiple README recommendations, how would automation choose which one is the best for the starterkit? Etc.

[jpl-jengelke]

Hi @jpl-jengelke - thanks for this ticket. I have some thoughts:

• I’m not so sure about making slim-starterkit the “canonical” version of all files. Not all SLIM deliverables will be applicable within the slim-starterkit repo, so I think we’ll have to keep in mind that the slim repo will have to be the authority for certain items. For example, written guides, non-GitHub related automation, etc.

Understood. This would only be for the deployable files, like the specific docs mentioned above that go into target repos.

An issue is that we are keeping multiple copies of product in different places. Which one will be primary? If we keep them in the main SLIM repository that raises the specter that they will be ungrouped and intermingled amongst implementation guides. I fear this would make the files more difficult to infuse, track and to disperse to consuming repos. The earlier decision was not to keep implementations in the main SLIM repository as a matter of pragmatism to demonstrate different technologies. Isolating them in a focused context limits conflating differences between language implementations. Should the policy be uniform for all products, both technology and documentation inclusive? We have the Python Starter Kit, for example, and will likely have the C Starter Kit, etc. which use build processes implied by the technologies.

• Adding version numbers to version controlled files (that have hashed versions already) may be overkill. We should be able to use Git hashes for version control from GitHub metadata.
• An automated solution sounds good but might be a bit complex to write and maintain.

The primary reason for this suggestion is to track infusions. So if a LICENSE or CODE_OF_CONDUCT changes for administrative or legal reasons, it will be possible to recognize older versions in any infused repo, even if they have been edited, as long as the version is correct. Moreover, it would clearly indicate if that document changed between commits (since not all docs may change). There are other ways to do this, like calculating checksums, but the utility narrows if the files are edited, and it becomes harder (though not impossible) to detect this.

Based on the above, I’m wondering if we can we investigate the option of ensuring the maintainers of the slim-starterkit have notifications set-up to be informed when the slim repo makes an updated merge of artifacts and for the maintainers to manually update repos like slim-starterkit and slim-starterkit-python, etc.? We might be able to use Dependabot dependency updates for this type of update. The reason I suggest this is that I’m unaware of major software projects that automatically update dependency references by version without a human in the loop. We might want to keep this process manual to ensure the integrity of the starterkit repos. For example, if we have multiple README recommendations, how would automation choose which one is the best for the starterkit? Etc.

That's another approach, but I would be interested to know how it would assess the examples provided above. Many software products, specifically messaging APIs, are standardized on contract versions independent from implementing software. Simple examples are protocols like HTTP, WADL, SMTP or often custom RESTful messages. GitHub Actions are versioned similarly. Amazon discusses versioning implementations in their architecture guide for service contracts. This implies that software can change and evolve but rely on backwards compatibility of documents that cross between software components. Similarly, I'm looking at SLIM documents as a contract that evolves independently from multiple commits that may compose an implementation guide. It may just be a way of looking at the product in isolation, but I think there are tangible benefits to track files meant for infusion.

I'm not suggesting that all of this is important but maybe how we settle on the actual mechanics may make some of it worth consideration.

[riverma]

Thanks @jpl-jengelke. Let's discuss this more in person and also let @NASA-AMMOS/slim-tsc weigh in.

I'm a little worried we're creating additional complexity than needed and setting ourselves up for future maintenance problems. My two cents are that the slim repository should remain the main "canonical" project repository for all deliverables that don't stand alone as separate, unique projects. The slim-starterkit isn't really a separate project, it's a collection of select files from the SLIM repo put together into a GitHub template. If someone came to us and asked for a GitLab project template we'd be in trouble, or one for a unique deployment venue we haven't thought of yet. Keeping the SLIM repo authoritative and then updating downstream uses (that are within our control) seems simpler to me than the other way around.