Skip to content
This repository has been archived by the owner on Mar 22, 2024. It is now read-only.

Remove helm docs from the build / release toolchain #405

Open
edwbuck opened this issue Jul 26, 2023 · 0 comments
Open

Remove helm docs from the build / release toolchain #405

edwbuck opened this issue Jul 26, 2023 · 0 comments
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request in-progress There is a pr for this issue

Comments

@edwbuck
Copy link
Contributor

edwbuck commented Jul 26, 2023

Helm docs has had a number of shortcomings, many of which we have managed to work around. But, three new items cannot be worked around, without maintaining large sections of the generated Markdown manually.

  1. There is no support for suppressing Values.yaml values, which means that the generated table of items is excessively large.
  2. There is no support for arbitrary reordering the Values.yaml values, which means that the only orderings that exist are 'in place ordering" and "alphabetical ordering". This limits the ability to group settings based on functionality, which makes the documentation (a component of the Helm Charts user interface) impossible to design around "areas of functionality".
  3. There is no support for adding Values.yaml items that aren't in the Values.yaml into the generated values tables. This is useful for scenarios where a purposefully missing value (like the trust domain name) is required but will not be in the Values.yaml file (to trigger helm install failures).

After extensive attempts to find solutions to these shortcomings, the only solution that seems viable is either to rewrite helm_docs or to maintain most of the previously generated output manually, replacing the helm_docs generated output.

On July 25th, 2023, the attending members of the maintainers meeting voted unanimously to remove the helm_docs. There is an additional Issue where some, if not all, of the generation might be implemented by a different markdown generator; but, to facilitate the transition, the scope of this issue is bounded to not include the additional work of adding the new generator. This issue is the "first" step of a larger overall replacement.

Scope:

  1. Generate the markdown from the helm_docs to maintain released documents as they exist today.
  2. Check those documents in, removing helm_docs and all related helm_docs tooling.
  3. Establish a Makefile target test if the original helm docs inputs are newer than the output README.MD.
    1. If the inputs are newer, the make command should exit in error.
    2. If the inputs are older, the make command should pass
  4. Update review procedures to run the command, to flag if a README.md update may be necessary
    1. If the tooling reports an update may be necessary, the reviewer will preform a diff on the various Values.yaml files
    2. if the various values.yaml files were updated (verified by diff) then the reviewer will fail any review that doesn't include Values.yaml updates.

This is only the minimum to complete this issue. Improvements on the process are welcome; but, the scope is to transition to manually maintained README.md files. Scope to transition from manually maintained README.md files to other technologies is constrained to a different Issue, so we can break this effort down into two steps.

@edwbuck edwbuck added documentation Improvements or additions to documentation enhancement New feature or request good first issue Good for newcomers help wanted Extra attention is needed labels Jul 26, 2023
@edwbuck edwbuck added in-progress There is a pr for this issue and removed good first issue Good for newcomers help wanted Extra attention is needed labels Aug 1, 2023
@edwbuck edwbuck self-assigned this Aug 1, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
documentation Improvements or additions to documentation enhancement New feature or request in-progress There is a pr for this issue
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant