Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation around version strategies #4220

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

selfdocumentingcode
Copy link

@selfdocumentingcode selfdocumentingcode commented Sep 21, 2024

Description

  • Improve listing of version strategies on "How it works" docs page
    • Update names to reflect recent code changes
    • Replace (incorrect) examples with a link to the main version strategies list
    • Use a stub for the TrackReleaseBranches description (working on updating this one as well)
  • Improve listing of version strategies on "Configuration" docs page
    • Replace TrunkBased strategy listing with Mainline
    • Mark TrackReleaseBranches as unused since technically it is an allowed value even though it's a noop.
  • Fix Edit Diagram link on "How it works" docs page
  • Update docs\readme.me build instructions to use correct target name for docs preview

Related Issue

#4219

Motivation and Context

I'm trying to understand how GitVersion works and the documentation makes it difficult at times.

How Has This Been Tested?

I built and ran a preview of /docs locally.

Checklist:

  • My code follows the code style of this project.
  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • I have added tests to cover my changes.
  • All new and existing tests passed.

@arturcic
Copy link
Member

  • Remove unused file docs\input\docs\references\mdsource\configuration.source.md

This one is actually used, and we have tests that check the content of the configuration.md based on the configuration.source.md. See #4104

@@ -25,8 +25,7 @@ public override void Setup(BuildContext context, ISetupContext info)
{ "BaseEditUrl", "https://github.com/gittools/GitVersion/tree/main/docs/input/" },
{ "SourceFiles", context.MakeAbsolute(Paths.Src) + "/**/{!bin,!obj,!packages,!*.Tests,!GitTools.*,}/**/*.cs" },
{ "Title", "GitVersion" },
{ "IncludeGlobalNamespace", false },
{ "IgnoreFolders", "**/mdsource" }
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be kept

@selfdocumentingcode
Copy link
Author

selfdocumentingcode commented Sep 23, 2024

I see. That feature is not mentioned anywhere in the readme file nor did any tests failed after removing it.

I will, of course, remove the change from the PR.
Thanks for pointing it out!

Edit: @arturcic I am right to assume that for this particular change I'm making to the configuration.md file, i.e. unrelated to the GitVersion workflows, I have to also make the same change in the configuration.source.md file in order for the change in configuration.md to not get reverted the next time the mkdocs.yml workflow runs?

@arturcic
Copy link
Member

I see. That feature is not mentioned anywhere in the readme file nor did any tests failed after removing it.

I will, of course, remove the change from the PR.
Thanks for pointing it out!

Edit: @arturcic I am right to assume that for this particular change I'm making to the configuration.md file, i.e. unrelated to the GitVersion workflows, I have to also make the same change in the configuration.source.md file in order for the change in configuration.md to not get reverted the next time the mkdocs.yml workflow runs?

Yes, please update the source file instead, as the configuration.md is updated from the source

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revert this change

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you also include the details for MarkdownSnippets that converts the *.source.md into *.md files in this readme?
This tool is used to embed some files into md files

https://github.com/GitTools/GitVersion/blob/main/.github/workflows/mkdocs.yml#L24-L28

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants