Keep config and schema unchanged during a release #5010
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This way it will also work when we make a copy of the entire docs folder.
The plan is to keep the original docs and schema folders unchanged for the duration of a release; we'll only continuously update the -master copies. Right before a new release we will copy them over.
This needs to be run immediately before creating a release. We could go further here and use gh to create the PR, but since I'm usually logged in with my work account to gh, this won't help me. The git push command prints the URL to create the PR, so it's a simple matter of command-clicking it, which is good enough for me.
…t up to date Of course it would be cooler if the workflow could create the PR and merge it if necessary, but this will have to do for now.
stefanhaller
added
the
maintenance
Coverage summary from CodacySee diff coverage on Codacy
Coverage variation details
Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: Diff coverage details
Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: See your quality gate settings Change summary preferencesFootnotes
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Some of our documentation is auto-generated from the source code (the defaults section in Config.md, and the keybinding cheat sheets), and so is the JSON schema for the config file. We have a check running on CI that verifies that when the source code changes (e.g. a new config option is added), those files are properly regenerated, to make sure they are always up to date with the latest version of the source code.
This causes a problem when people look at the documentation for a newly added config option and wonder why it doesn't work in the lazygit version they are using. Lots of issues were filed where people report this as a bug, and we have to patiently explain to them that the documentation describes a feature that hasn't been released yet. A similar problem occurs when we rename a config option (as has recently happened with the 'paging' config, which was renamed to 'pagers' in #4953), in which case the user's editor (if it supports JSON validation against the jsonschema store) starts to complain about the old config, even though it still works, and the new one doesn't yet.
To solve this, keep the documentation and the JSON schema unchanged for the lifetime of a release; make those continuous changes in a separate copy of those folders, and only copy the files back to the real location right before we make a release. To facilitate this, we add a script to conveniently create a PR for copying the files back, and add a check to the release workflow to abort with an error if this was forgotten.
Note that we only use this approach in order to solve the problem with the auto-generated files; this has a consequence for making changes to the other, non-auto-generated parts of the docs. For example, when fixing a spelling error, rewording a paragraph to explain it better, or adding an entirely new file, those changes will now have to be made in docs-master, which means:
docsaccidentally, it will be reverted with the next release.We can mitigate 2. by making the identical change in both places, but I think we should first wait and see how often it happens, and whether it is actually a problem.