Improve documentation around version strategies #4220

selfdocumentingcode · 2024-09-21T13:09:57Z

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
- Concisely describe Mainline and TrackReleaseBranches version strategies
Improve listing of version strategies on "Configuration" docs page
- Replace TrunkBased strategy listing with Mainline
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 · 2024-09-23T08:05:21Z

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

arturcic · 2024-09-23T09:05:58Z

build/docs/BuildLifetime.cs

@@ -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" }


This should be kept

selfdocumentingcode · 2024-09-23T17:42:42Z

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 · 2024-09-23T17:53:54Z

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

docs/input/docs/reference/mdsource/configuration.source.md

docs/readme.md

arturcic · 2024-10-01T13:49:13Z

@HHobeck can you check the changes for the documentations?

HHobeck · 2024-10-01T13:57:31Z

@HHobeck can you check the changes for the documentations?

Yes, I try to do the review tomorrow.

docs/input/docs/learn/how-it-works.md

HHobeck

May I ask you to document this? #4248

Updated the configuration documentation to specify that the order in which version strategies are specified does not matter.

selfdocumentingcode · 2024-10-11T16:12:42Z

May I ask you to document this? #4248

Sure! Check my latest commits.

arturcic · 2024-10-11T16:16:44Z

@HHobeck if there are no additional changes that need to be added, please merge this PR

HHobeck · 2024-10-11T17:38:21Z

@HHobeck if there are no additional changes that need to be added, please merge this PR

Not sure why just the auto merge option is shown

arturcic · 2024-10-11T19:36:56Z

I disabled auto-merge, but because there are some required actions (that are not run because only docs where changed) it's in pending state, so I will just merge

mergify · 2024-10-11T19:37:37Z

Thank you @selfdocumentingcode for your contribution!

gittools-bot · 2024-10-15T10:32:35Z

🎉 This issue has been resolved in version 6.0.3 🎉
The release is available on:

Your GitReleaseManager bot 📦🚀

selfdocumentingcode added 2 commits September 21, 2024 14:52

Improve listing of version strategies in how-it-works.md

9926123

Fix Edit Diagram link on how-it-works.md

5cd8b00

selfdocumentingcode mentioned this pull request Sep 21, 2024

[Docs]: Confusing/missing documentation around strategies #4219

Closed

2 tasks

arturcic self-assigned this Sep 22, 2024

arturcic requested changes Sep 23, 2024

View reviewed changes

Use correct target name in docs build instructions readme

c733fbb

selfdocumentingcode added 2 commits September 23, 2024 20:03

Replace TrunkBased strategy listing with Mainline

0d36695

Update description of Mainline strategy in how-it-works

c3bf45b

arturcic requested changes Sep 23, 2024

View reviewed changes

docs/input/docs/reference/mdsource/configuration.source.md Outdated Show resolved Hide resolved

docs/readme.md Outdated Show resolved Hide resolved

HHobeck reviewed Oct 2, 2024

View reviewed changes

docs/input/docs/learn/how-it-works.md Outdated Show resolved Hide resolved

selfdocumentingcode added 2 commits October 3, 2024 17:20

Update description of TrackReleaseBranches version strategy

05d11f5

fixup! Update description of Mainline strategy in how-it-works

e18d6b1

HHobeck self-requested a review October 8, 2024 12:42

HHobeck reviewed Oct 8, 2024

View reviewed changes

selfdocumentingcode added 3 commits October 11, 2024 18:08

Clarify version strategy order in documentation

6f76020

Updated the configuration documentation to specify that the order in which version strategies are specified does not matter.

Further document Fallback strategy

1750d00

Re-order strategies in how-it-works to match rest of documentation pages

5f4ca13

arturcic added the documentation label Oct 11, 2024

arturcic added this to the 6.x milestone Oct 11, 2024

HHobeck approved these changes Oct 11, 2024

View reviewed changes

HHobeck enabled auto-merge (rebase) October 11, 2024 17:36

arturcic disabled auto-merge October 11, 2024 19:35

arturcic merged commit baaab9a into GitTools:main Oct 11, 2024
6 checks passed

arturcic modified the milestones: 6.x, 6.0.3 Oct 15, 2024

arturcic linked an issue Oct 17, 2024 that may be closed by this pull request

[Docs]: Confusing/missing documentation around strategies #4219

Closed

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Improve documentation around version strategies #4220

Improve documentation around version strategies #4220

Uh oh!

selfdocumentingcode commented Sep 21, 2024 •

edited

Loading

Uh oh!

arturcic commented Sep 23, 2024

Uh oh!

arturcic Sep 23, 2024

Uh oh!

selfdocumentingcode commented Sep 23, 2024 •

edited

Loading

Uh oh!

arturcic commented Sep 23, 2024

Uh oh!

Uh oh!

Uh oh!

arturcic commented Oct 1, 2024

Uh oh!

HHobeck commented Oct 1, 2024

Uh oh!

Uh oh!

HHobeck left a comment

Uh oh!

selfdocumentingcode commented Oct 11, 2024

Uh oh!

arturcic commented Oct 11, 2024

Uh oh!

HHobeck commented Oct 11, 2024

Uh oh!

arturcic commented Oct 11, 2024

Uh oh!

Uh oh!

mergify bot commented Oct 11, 2024

Uh oh!

gittools-bot commented Oct 15, 2024

Uh oh!

Uh oh!

Improve documentation around version strategies #4220

Improve documentation around version strategies #4220

Uh oh!

Conversation

selfdocumentingcode commented Sep 21, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue

Motivation and Context

How Has This Been Tested?

Checklist:

Uh oh!

arturcic commented Sep 23, 2024

Uh oh!

arturcic Sep 23, 2024

Choose a reason for hiding this comment

Uh oh!

selfdocumentingcode commented Sep 23, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

arturcic commented Sep 23, 2024

Uh oh!

Uh oh!

Uh oh!

arturcic commented Oct 1, 2024

Uh oh!

HHobeck commented Oct 1, 2024

Uh oh!

Uh oh!

HHobeck left a comment

Choose a reason for hiding this comment

Uh oh!

selfdocumentingcode commented Oct 11, 2024

Uh oh!

arturcic commented Oct 11, 2024

Uh oh!

HHobeck commented Oct 11, 2024

Uh oh!

arturcic commented Oct 11, 2024

Uh oh!

Uh oh!

mergify bot commented Oct 11, 2024

Uh oh!

gittools-bot commented Oct 15, 2024

Uh oh!

Uh oh!

selfdocumentingcode commented Sep 21, 2024 •

edited

Loading

selfdocumentingcode commented Sep 23, 2024 •

edited

Loading