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

Overhaul Main Workflow Docs #107415

Merged
merged 20 commits into from
Sep 16, 2024
Merged

Overhaul Main Workflow Docs #107415

merged 20 commits into from
Sep 16, 2024

Conversation

ivdiazsa
Copy link
Member

@ivdiazsa ivdiazsa commented Sep 5, 2024

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.

@dotnet-issue-labeler dotnet-issue-labeler bot 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
Copy link
Member

@lambdageek lambdageek left a comment

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.

docs/workflow/README.md Outdated Show resolved Hide resolved
docs/workflow/README.md Outdated Show resolved Hide resolved
@ivdiazsa ivdiazsa added this to the 10.0.0 milestone Sep 9, 2024
…oss-compiling to the general workflow introduction segment.
docs/workflow/README.md Outdated Show resolved Hide resolved
docs/workflow/README.md Outdated Show resolved Hide resolved
docs/workflow/README.md Outdated Show resolved Hide resolved
docs/workflow/README.md Outdated Show resolved Hide resolved
docs/workflow/building/coreclr/README.md Outdated Show resolved Hide resolved
docs/workflow/building/coreclr/README.md Outdated Show resolved Hide resolved
docs/workflow/building/coreclr/README.md Outdated Show resolved Hide resolved
docs/workflow/requirements/linux-requirements.md Outdated Show resolved Hide resolved
docs/workflow/using-docker.md Outdated Show resolved Hide resolved
docs/workflow/using-docker.md Outdated Show resolved Hide resolved
Copy link
Member

@mikelle-rogers mikelle-rogers left a comment

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!

docs/workflow/README.md Outdated Show resolved Hide resolved
docs/workflow/README.md Show resolved Hide resolved
docs/workflow/README.md Outdated Show resolved Hide resolved
docs/workflow/README.md Outdated Show resolved Hide resolved
docs/workflow/README.md Outdated Show resolved Hide resolved
docs/workflow/building/coreclr/README.md Outdated Show resolved Hide resolved
docs/workflow/building/coreclr/README.md Show resolved Hide resolved
docs/workflow/requirements/linux-requirements.md Outdated Show resolved Hide 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
13 checks passed
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
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