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

Initial documentation for GitHub dependency graph integration #86

Merged
merged 26 commits into from Jun 26, 2023

Conversation

michaelbprice
Copy link
Contributor

@michaelbprice michaelbprice commented May 23, 2023

These changes add initial documentation for the feature in the vcpkg-tool PR at microsoft/vcpkg-tool#989.

The goal here is to:

  1. Provide enough usage guidance that users can try out the experimental feature.
  2. Draw attention to the experimental nature and to solicit feedback on the feature.

The most notable thing about this PR is that creates an "Experimental features" page that we can put information about these types of experiments. This way, we don't "pollute" the non-experimental feature documentation. This also allows us to avoid prematurely restructuring documentation based on the presence of an experimental feature.

Missing pieces:

  • It currently needs more notes on known limitations, but we can also keep this list updated as we get user feedback.
  • Does it need a change to index.yml?

@prmerger-automator
Copy link

@michaelbprice : Thanks for your contribution! The author(s) have been notified to review your proposed change.

@learn-build-service-prod
Copy link
Contributor

Learn Build status updates of commit 99e9f73:

⚠️ Validation status: warnings

File Status Preview URL Details
vcpkg/users/github-dependency-graph.md ⚠️Warning View Details
vcpkg/TOC.yml ✅Succeeded View

vcpkg/users/github-dependency-graph.md

  • Line 10, Column 1: [Warning: h1-not-first - See documentation] Markdown content is not allowed before H1 'About the GitHub dependency graph'.
  • Line 14, Column 1: [Warning: multiple-h1s - See documentation] Multiple H1s(H1 'vcpkg integration with the GitHub depdency graph') are not allowed. You can only have one top-level heading.
  • Line 27, Column 1: [Warning: multiple-h1s - See documentation] Multiple H1s(H1 'Known limitations') are not allowed. You can only have one top-level heading.
  • Line 34, Column 1: [Warning: multiple-h1s - See documentation] Multiple H1s(H1 'Example GitHub Actions workflow') are not allowed. You can only have one top-level heading.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

@michaelbprice
Copy link
Contributor Author

Pinging @dan-shaw for additional input. Apparently, I cannot add reviewers.

@learn-build-service-prod
Copy link
Contributor

Learn Build status updates of commit 86bb8da:

✅ Validation status: passed

File Status Preview URL Details
vcpkg/TOC.yml ✅Succeeded View
vcpkg/users/github-dependency-graph.md ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

@prmerger-automator
Copy link

PRMerger Results

Issue Description
Added File(s) This PR contains added files. New files require human review.
Yaml File(s) This PR includes changes to .yml file(s) owned by another author.
File Change Percent This PR contains file(s) with more than 30% file change.

vcpkg/users/github-dependency-graph.md Outdated Show resolved Hide resolved
vcpkg/users/github-dependency-graph.md Outdated Show resolved Hide resolved
vcpkg/users/github-dependency-graph.md Outdated Show resolved Hide resolved
@michaelbprice
Copy link
Contributor Author

Should I also link to the demo template repository I have set up (it's not public yet, but if we wanted to, I could make it public when we merge this).

vcpkg/users/github-dependency-graph.md Outdated Show resolved Hide resolved
vcpkg/users/github-dependency-graph.md Outdated Show resolved Hide resolved
vcpkg/users/github-dependency-graph.md Outdated Show resolved Hide resolved
vcpkg/users/github-dependency-graph.md Outdated Show resolved Hide resolved
vcpkg/TOC.yml Outdated Show resolved Hide resolved
vcpkg/users/github-dependency-graph.md Outdated Show resolved Hide resolved
vcpkg/users/github-dependency-graph.md Outdated Show resolved Hide resolved
@learn-build-service-prod
Copy link
Contributor

Learn Build status updates of commit df2cb27:

✅ Validation status: passed

File Status Preview URL Details
vcpkg/TOC.yml ✅Succeeded View
vcpkg/users/github-dependency-graph.md ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

@prmerger-automator
Copy link

PRMerger Results

Issue Description
Added File(s) This PR contains added files. New files require human review.
Yaml File(s) This PR includes changes to .yml file(s) owned by another author.
File Change Percent This PR contains file(s) with more than 30% file change.

@michaelbprice michaelbprice marked this pull request as ready for review June 12, 2023 21:53
…e experimental notice to be more consistent with other experiments.
@learn-build-service-prod
Copy link
Contributor

Learn Build status updates of commit 8054107:

✅ Validation status: passed

File Status Preview URL Details
vcpkg/TOC.yml ✅Succeeded View
vcpkg/users/github-dependency-graph.md ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

@prmerger-automator
Copy link

PRMerger Results

Issue Description
Added File(s) This PR contains added files. New files require human review.
Yaml File(s) This PR includes changes to .yml file(s) owned by another author.
File Change Percent This PR contains file(s) with more than 30% file change.

@learn-build-service-prod
Copy link
Contributor

Learn Build status updates of commit 7e25c20:

✅ Validation status: passed

File Status Preview URL Details
vcpkg/github-integration.md ✅Succeeded View
vcpkg/TOC.yml ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

@prmerger-automator
Copy link

PRMerger Results

Issue Description
Added File(s) This PR contains added files. New files require human review.
Yaml File(s) This PR includes changes to .yml file(s) owned by another author.
Commits Count This PR contains more than 15 commits.
File Change Percent This PR contains file(s) with more than 30% file change.

@learn-build-service-prod
Copy link
Contributor

Learn Build status updates of commit a20b2bc:

✅ Validation status: passed

File Status Preview URL Details
vcpkg/github-integration.md ✅Succeeded View
vcpkg/TOC.yml ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

@prmerger-automator
Copy link

PRMerger Results

Issue Description
Added File(s) This PR contains added files. New files require human review.
Yaml File(s) This PR includes changes to .yml file(s) owned by another author.
Commits Count This PR contains more than 15 commits.
File Change Percent This PR contains file(s) with more than 30% file change.

@michaelbprice
Copy link
Contributor Author

The implementation PR got merged today. I'll work with @dan-shaw to see if any updates here are warranted. @TylerMSFT - since you requested changes, it might require you to do an approval before merging. Would you be available tomorrow for that?

@TylerMSFT
Copy link
Member

TylerMSFT commented Jun 20, 2023 via email

Copy link
Member

@TylerMSFT TylerMSFT left a comment

Choose a reason for hiding this comment

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

Provisionally approving - please address as many of the comments I left as makes sense to you. I'm booked today and tomorrow, but Thurs will review the published article.

vcpkg/TOC.yml Outdated Show resolved Hide resolved
vcpkg/github-integration.md Outdated Show resolved Hide resolved
vcpkg/github-integration.md Outdated Show resolved Hide resolved
vcpkg/github-integration.md Outdated Show resolved Hide resolved
I've left the casing of vcpkg untouched, even at the start of a sentence, due to product specific guidelines.
@learn-build-service-prod
Copy link
Contributor

Learn Build status updates of commit d399ceb:

✅ Validation status: passed

File Status Preview URL Details
vcpkg/github-integration.md ✅Succeeded View
vcpkg/TOC.yml ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

@prmerger-automator
Copy link

PRMerger Results

Issue Description
Added File(s) This PR contains added files. New files require human review.
Yaml File(s) This PR includes changes to .yml file(s) owned by another author.
Commits Count This PR contains more than 15 commits.
File Change Percent This PR contains file(s) with more than 30% file change.

Copy link
Member

@TylerMSFT TylerMSFT left a comment

Choose a reason for hiding this comment

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

good to go from my side

@learn-build-service-prod
Copy link
Contributor

Learn Build status updates of commit cad13bd:

✅ Validation status: passed

File Status Preview URL Details
vcpkg/github-integration.md ✅Succeeded View
vcpkg/TOC.yml ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

@prmerger-automator
Copy link

PRMerger Results

Issue Description
Added File(s) This PR contains added files. New files require human review.
Yaml File(s) This PR includes changes to .yml file(s) owned by another author.
Commits Count This PR contains more than 15 commits.
File Change Percent This PR contains file(s) with more than 30% file change.

Co-authored-by: Victor Romero <romerosanchezv@gmail.com>
@learn-build-service-prod
Copy link
Contributor

Learn Build status updates of commit e0c1136:

✅ Validation status: passed

File Status Preview URL Details
vcpkg/github-integration.md ✅Succeeded View
vcpkg/TOC.yml ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

@prmerger-automator
Copy link

PRMerger Results

Issue Description
Added File(s) This PR contains added files. New files require human review.
Yaml File(s) This PR includes changes to .yml file(s) owned by another author.
Commits Count This PR contains more than 15 commits.
File Change Percent This PR contains file(s) with more than 30% file change.

vcpkg/github-integration.md Outdated Show resolved Hide resolved
vicroms and others added 2 commits June 26, 2023 14:28
Co-authored-by: Augustin Popa <AugP@users.noreply.github.com>
@learn-build-service-prod
Copy link
Contributor

Learn Build status updates of commit 274884b:

✅ Validation status: passed

File Status Preview URL Details
vcpkg/github-integration.md ✅Succeeded View
vcpkg/TOC.yml ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

@prmerger-automator
Copy link

PRMerger Results

Issue Description
Added File(s) This PR contains added files. New files require human review.
Yaml File(s) This PR includes changes to .yml file(s) owned by another author.
Commits Count This PR contains more than 15 commits.
File Change Percent This PR contains file(s) with more than 30% file change.

@learn-build-service-prod
Copy link
Contributor

Learn Build status updates of commit 95439d3:

✅ Validation status: passed

File Status Preview URL Details
vcpkg/github-integration.md ✅Succeeded View
vcpkg/TOC.yml ✅Succeeded View

For more details, please refer to the build report.

For any questions, please:

@prmerger-automator
Copy link

PRMerger Results

Issue Description
Added File(s) This PR contains added files. New files require human review.
Yaml File(s) This PR includes changes to .yml file(s) owned by another author.
Commits Count This PR contains more than 15 commits.
File Change Percent This PR contains file(s) with more than 30% file change.

@AugP AugP merged commit d119002 into microsoft:main Jun 26, 2023
2 checks passed
vicroms added a commit that referenced this pull request Jun 27, 2023
* Add docs for x-gha.

* Add mention of --x-binary-cache-github-actions.

* ACTIONS_CACHE_URL is the actual name

* Revert "Add mention of --x-binary-cache-github-actions."

This reverts commit f6ee7de.

* Add environment variables reference

* Improve GitHub Actions binary caching docs

This adds clarification as to why the GHA binary caching provider is
using environment variables for configuration.

* fix

* fix

* fix

* fix

* fix

* fix

* fix

* guidance for usage files

* add usage example and fix formatting

* format

* Remove internal only facing documents.

* Fix misspellings

* wip

* Add missing depend-info entry to the table of contents.

* Update depend-info for --format.

* modify usage instructions

* Change title

* remove absolute links

* Update binarycaching.md

Changed first person wording to third person

* Update binarycaching.md

Minor grammatical fixes, changed first person to third person

* update depend-info documentation with mermaid support and format changes

* change examples to match our heuristics

* CPub style

* update main help message with mermaid support

* Initial documentation for GitHub dependency graph integration (#86)

* Adding an initial description of the experimental vcpkg integration with GitHub dependency graph.

* Adding an experimental features section to the documentation and adding the GitHub dependency graph page in there.

* Be more explicit about how to contact us with feedback.

* Fixing heading issues identified by GitHub Actions check

* Fixing a few minor issues.

* Adding text explaining how to enable dependency graph and updating the experimental notice to be more consistent with other experiments.

* Renaming file for GitHub integrations info and moving round in the TOC structure

* Fixing Learn publishing validation errors.

* Updating doc header information

* Updating headers to reflect that multiple topics will be covered on this page

* Adding high-level summary of the GitHub Packages caching integration

* Wording changes as suggested by @vicroms with very small tweaks.

* Fixing 2 incorrect paths to the experimental block.

* Updating some wording that I felt was too awkward and adding a note on having a vcpkg.json manifest for the example.

* Removing locales from linked-to URLs.

* Removing "Additionally" since it's an empty word.

* code blocking 'gh' to avoid machine translation issues (and to make it stand out more from the text).

* Moving GitHub Integration from the doc root to Consuming Libraries section

* Addressing feedback from @TylerMSFT and fixing link to file issues (against vcpkg instead of vcpkg-docs).

* Adding some nice and short anchor text to important sections (for better incoming links).

* Applying further copy-editing suggestions from @TylerMSFT.

I've left the casing of vcpkg untouched, even at the start of a sentence, due to product specific guidelines.

* Adding explicitly which version of vcpkg is required to enabled the feature.

* Applied comment from Victor on vcpkg/github-integration.md

Co-authored-by: Victor Romero <romerosanchezv@gmail.com>

* Apply comment suggestion on vcpkg/github-integration.md

Co-authored-by: Augustin Popa <AugP@users.noreply.github.com>

* Removed an unnecessary newline

---------

Co-authored-by: Augustin Popa <AugP@users.noreply.github.com>
Co-authored-by: Victor Romero <romerosanchezv@gmail.com>

* Feature/license features (#93)

* Add docs for licenses in features

* Update vcpkg/reference/vcpkg-json.md

---------

Co-authored-by: Augustin Popa <AugP@users.noreply.github.com>

* Updated repo notification recipients .openpublishing.publish.config.json

* Revert "Add guidance for handling usage files"

---------

Co-authored-by: quyykk <quyykk@protonmail.com>
Co-authored-by: Paul J. Davis <paul.davis@tiledb.com>
Co-authored-by: dan-shaw <51385773+dan-shaw@users.noreply.github.com>
Co-authored-by: Javier Matos Denizac <javier.matosd@gmail.com>
Co-authored-by: Billy Robert O'Neal III <bion@microsoft.com>
Co-authored-by: myd7349 <myd7349@gmail.com>
Co-authored-by: Robert Schumacher <roschuma@microsoft.com>
Co-authored-by: Wim Leflere <wim.leflere@gmail.com>
Co-authored-by: Victor Romero <viromer@microsoft.com>
Co-authored-by: Michael B. Price <michael.b.price.dev@gmail.com>
Co-authored-by: Victor Romero <romerosanchezv@gmail.com>
Co-authored-by: autoantwort <41973254+autoantwort@users.noreply.github.com>
vicroms added a commit that referenced this pull request Jun 29, 2023
* Add docs for x-gha.

* Add mention of --x-binary-cache-github-actions.

* ACTIONS_CACHE_URL is the actual name

* Revert "Add mention of --x-binary-cache-github-actions."

This reverts commit f6ee7de.

* Add environment variables reference

* Improve GitHub Actions binary caching docs

This adds clarification as to why the GHA binary caching provider is
using environment variables for configuration.

* fix

* fix

* fix

* fix

* fix

* fix

* fix

* guidance for usage files

* add usage example and fix formatting

* format

* Remove internal only facing documents.

* Fix misspellings

* wip

* Add missing depend-info entry to the table of contents.

* Update depend-info for --format.

* modify usage instructions

* Change title

* remove absolute links

* Update binarycaching.md

Changed first person wording to third person

* Update binarycaching.md

Minor grammatical fixes, changed first person to third person

* update depend-info documentation with mermaid support and format changes

* change examples to match our heuristics

* CPub style

* update main help message with mermaid support

* Initial documentation for GitHub dependency graph integration (#86)

* Adding an initial description of the experimental vcpkg integration with GitHub dependency graph.

* Adding an experimental features section to the documentation and adding the GitHub dependency graph page in there.

* Be more explicit about how to contact us with feedback.

* Fixing heading issues identified by GitHub Actions check

* Fixing a few minor issues.

* Adding text explaining how to enable dependency graph and updating the experimental notice to be more consistent with other experiments.

* Renaming file for GitHub integrations info and moving round in the TOC structure

* Fixing Learn publishing validation errors.

* Updating doc header information

* Updating headers to reflect that multiple topics will be covered on this page

* Adding high-level summary of the GitHub Packages caching integration

* Wording changes as suggested by @vicroms with very small tweaks.

* Fixing 2 incorrect paths to the experimental block.

* Updating some wording that I felt was too awkward and adding a note on having a vcpkg.json manifest for the example.

* Removing locales from linked-to URLs.

* Removing "Additionally" since it's an empty word.

* code blocking 'gh' to avoid machine translation issues (and to make it stand out more from the text).

* Moving GitHub Integration from the doc root to Consuming Libraries section

* Addressing feedback from @TylerMSFT and fixing link to file issues (against vcpkg instead of vcpkg-docs).

* Adding some nice and short anchor text to important sections (for better incoming links).

* Applying further copy-editing suggestions from @TylerMSFT.

I've left the casing of vcpkg untouched, even at the start of a sentence, due to product specific guidelines.

* Adding explicitly which version of vcpkg is required to enabled the feature.

* Applied comment from Victor on vcpkg/github-integration.md



* Apply comment suggestion on vcpkg/github-integration.md



* Removed an unnecessary newline

---------




* Feature/license features (#93)

* Add docs for licenses in features

* Update vcpkg/reference/vcpkg-json.md

---------



* Updated repo notification recipients .openpublishing.publish.config.json

* Revert "Add guidance for handling usage files"

---------

Co-authored-by: Robert Schumacher <roschuma@microsoft.com>
Co-authored-by: Augustin Popa <AugP@users.noreply.github.com>
Co-authored-by: quyykk <quyykk@protonmail.com>
Co-authored-by: Paul J. Davis <paul.davis@tiledb.com>
Co-authored-by: dan-shaw <51385773+dan-shaw@users.noreply.github.com>
Co-authored-by: Javier Matos Denizac <javier.matosd@gmail.com>
Co-authored-by: Billy Robert O'Neal III <bion@microsoft.com>
Co-authored-by: myd7349 <myd7349@gmail.com>
Co-authored-by: Wim Leflere <wim.leflere@gmail.com>
Co-authored-by: Michael B. Price <michael.b.price.dev@gmail.com>
Co-authored-by: autoantwort <41973254+autoantwort@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

6 participants