Skip to content

Overhaul Main Workflow Docs - #107415

Merged
ivdiazsa merged 20 commits into
dotnet:mainfrom
ivdiazsa:new-flowing-docs
Sep 16, 2024
Merged

ivdiazsa merged 20 commits into
dotnet:mainfrom
ivdiazsa:new-flowing-docs

Conversation

@ivdiazsa

@ivdiazsa ivdiazsa commented Sep 5, 2024

Copy link
Copy Markdown
Contributor

This PR aims to make the experience of the Workflow documentation of the runtime repo simpler and more accessible to the general public.

A summary of the changes made in this PR:

  • Overhaul the main Workflow README to cover all the basics right off the bat so users and contributors get a solid idea on how to begin working on the repo.
  • Condensed all the individual OS instructions for building CoreCLR into a single README, as they contained a lot of duplicate information that resulted in more clicks, more searching, and potentially more confusing.
  • Added information to the Building CoreCLR README about how to work in conjunction with other subsets and linking to the corresponding docs.
  • Updated a few pieces of information to better match today's status of the repo.
  • Rearranged and rephrased a few things in the requirements docs so that the instructions flow more naturally with the workflow one would follow on a new machine.
  • Overall rephrased some instructions so that they roll off the tongue more smoothly when reading them and are easier to understand.

Ideas for follow-up work (in this PR and/or other subsequent PR's):

  • Merge the CoreCLR and Libraries cross-building docs, as they have lots of things in common.
  • Maybe we can make a general building doc and only defer to helper docs the things unique to CoreCLR, Libraries, and Mono.
  • Start overhauling other sectors of the documentation such as testing and debugging like this PR does. Make sure the information is up to date, avoid excessive redirections to other docs, rephrase as necessary for a more natural tone, etc.

@ghost ghost added the needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners label Sep 5, 2024
@ivdiazsa ivdiazsa added documentation Documentation bug or enhancement, does not impact product or test code and removed needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners labels Sep 5, 2024

@lambdageek lambdageek left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I think it's useful right off the bat to establish that for some workflows cross-compilation is the expected approach.

Comment thread docs/workflow/README.md Resolved
Comment thread docs/workflow/README.md Resolved
@ivdiazsa ivdiazsa added this to the 10.0.0 milestone Sep 9, 2024
…oss-compiling to the general workflow introduction segment.
Comment thread docs/workflow/README.md Resolved
Comment thread docs/workflow/README.md Resolved
Comment thread docs/workflow/README.md Resolved
Comment thread docs/workflow/README.md Resolved
Comment thread docs/workflow/using-docker.md Resolved
Comment thread docs/workflow/using-docker.md Resolved

@mikelle-rogers mikelle-rogers left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks for putting this together!

Comment thread docs/workflow/README.md Resolved
Comment thread docs/workflow/README.md Resolved
Comment thread docs/workflow/README.md Resolved
Comment thread docs/workflow/README.md Resolved
Comment thread docs/workflow/README.md Resolved
…g to make the docs more friendly and clear as per received feedback.
@ivdiazsa ivdiazsa linked an issue Sep 16, 2024 that may be closed by this pull request
5 tasks
@ivdiazsa
ivdiazsa merged commit b3d440f into dotnet:main Sep 16, 2024
jtschuster pushed a commit to jtschuster/runtime that referenced this pull request Sep 17, 2024
* Started the Quality Week work of improving the workflow docs.

* Made more progress on the general workflow README doc, as well as the CoreCLR one.

* Rephrased some things to make them roll off the tongue better, and fixed a couple spelling and grammatical mistakes.

* Basically finished the main  workflow README, and the CoreCLR building docs.

* Almost done with the CoreCLR building docs, finished the MacOS requirements one, and got far enough on the Windows requirements one.

* Finished the first pass on the Windows requirements doc.

* Finished the first pass of the Linux Environment Requirements.

* Finished the first pass of the Linux requirements doc.

* Made good progress on the 'Using Docker' new doc.

* Finished the first pass of the Using Docker doc.

* Initial merging of the new docs with the existing documentation.

* Improved the redaction of some sentences, improved some formatting, and fixed a few broken links.

* Forgot to commit a NativeAOT note.

* Removed the cross signs in the tables and added general info about cross-compiling to the general workflow introduction segment.

* Added some redaction improvements, and corrected a few misleading and/or outdated details.

* Linked the Workflow's README to the CoreCLR Building README.

* Added a few additional details, and improved some wording and phrasing to make the docs more friendly and clear as per received feedback.

* Fixed typo in the -DCLR_CMAKE_APPLE_DYSM=TRUE flags.
sirntar pushed a commit to sirntar/runtime that referenced this pull request Sep 30, 2024
* Started the Quality Week work of improving the workflow docs.

* Made more progress on the general workflow README doc, as well as the CoreCLR one.

* Rephrased some things to make them roll off the tongue better, and fixed a couple spelling and grammatical mistakes.

* Basically finished the main  workflow README, and the CoreCLR building docs.

* Almost done with the CoreCLR building docs, finished the MacOS requirements one, and got far enough on the Windows requirements one.

* Finished the first pass on the Windows requirements doc.

* Finished the first pass of the Linux Environment Requirements.

* Finished the first pass of the Linux requirements doc.

* Made good progress on the 'Using Docker' new doc.

* Finished the first pass of the Using Docker doc.

* Initial merging of the new docs with the existing documentation.

* Improved the redaction of some sentences, improved some formatting, and fixed a few broken links.

* Forgot to commit a NativeAOT note.

* Removed the cross signs in the tables and added general info about cross-compiling to the general workflow introduction segment.

* Added some redaction improvements, and corrected a few misleading and/or outdated details.

* Linked the Workflow's README to the CoreCLR Building README.

* Added a few additional details, and improved some wording and phrasing to make the docs more friendly and clear as per received feedback.

* Fixed typo in the -DCLR_CMAKE_APPLE_DYSM=TRUE flags.
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 17, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

documentation Documentation bug or enhancement, does not impact product or test code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Refactor and Update Main Workflow Documentation

6 participants