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

Keep configuration.md file in sync with the changes in code #4104

Merged
merged 5 commits into from
Jul 19, 2024

Conversation

arturcic
Copy link
Member

@arturcic arturcic commented Jul 17, 2024

Closes #4017

In this PR I made it possible that whenever the workflow configuration changes, it gets also synced with the configuration.md file.

This is the way it is achieved:

  1. There is a test CheckWorkflowsAreUpdated that creates a new Configuration for the workflow and check if the serialized version matches the approved version. If not, then you need to accept the new changes and run again the test.
  2. When a dotnet build is performed, the approved files are copied to the docs (synced)
  3. There is a new GitHub Actions Workflow - mkdocs.yml, that embeds the changes into configuration.md using the MarkdownSnippets.Tool.

This tool takes a *.source.md file as input and embeds the content of the file similar to

snippet: /docs/workflows/GitFlow/v1.yml

The *.source.md file is located in a mdsource folder and excluded on docs publishing. (mdsource-directory)

The new updated result file is committed and pushed by the GitHub Action.

The nice thing about the embedding is that the tools also adds nice links similar to

image

@arturcic arturcic changed the title Feature/4017 Keep configuration.md file in sync with the changes in code Jul 17, 2024
@arturcic arturcic force-pushed the feature/4017 branch 7 times, most recently from da65ea6 to a3ed70a Compare July 18, 2024 09:34
If the configuration for a workflow will change the unit test will fail and will require to accept the new changes. These changes are then copied to the docs
@HHobeck
Copy link
Contributor

HHobeck commented Jul 18, 2024

Hi @arturcic.

Thank you that you are going to fix this. We have at the moment three sources right?

  1. ConfigurationBuilder (programmatically),
  2. docs/input/docs/workflows/ folder and
  3. the configuration.md

Is your plan to consolidate all three sources into one?

@arturcic
Copy link
Member Author

Hi @arturcic.

Thank you that you are going to fix this. We have at the moment three sources right?

  1. ConfigurationBuilder (programmatically),
  2. docs/input/docs/workflows/ folder and
    1. the configuration.md

Is your plan to consolidate all three sources into one?

Yes, that is part of this PR

ConfigurationBuilder - is the primary source, the rest gets updated.

ConfigurationBuilder -> docs/input/docs/workflows/ (via Copy files from approved folder)
docs/input/docs/workflows/ -> configuration.md (via configuration.source.md)

@arturcic arturcic marked this pull request as draft July 18, 2024 10:56
@HHobeck
Copy link
Contributor

HHobeck commented Jul 18, 2024

I'm not sure if you have seen it. But important to notice is that the docs/input/docs/workflows/ files are included in GitVersion.Configuration.dll as embedded resources.

image

@arturcic
Copy link
Member Author

I'm not sure if you have seen it. But important to notice is that the docs/input/docs/workflows/ files are included in GitVersion.Configuration.dll as embedded resources.

image

image

@arturcic arturcic requested review from HHobeck and asbjornu July 18, 2024 13:23
@arturcic arturcic marked this pull request as ready for review July 18, 2024 13:23
@HHobeck
Copy link
Contributor

HHobeck commented Jul 19, 2024

Very well. Good work. :)

@arturcic arturcic merged commit 0d2d67c into GitTools:main Jul 19, 2024
153 checks passed
@arturcic arturcic deleted the feature/4017 branch July 19, 2024 07:04
Copy link
Contributor

mergify bot commented Jul 19, 2024

Thank you @arturcic for your contribution!

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.

Verifies the contents of configuration.md against the default serialized configuration
2 participants