Runtime: organize markdown files

[danmosemsft]

We have lots of markdown files relating to building, debugging, issue management, style, API reviews and suchlike. These are mostly inherited from the original repos and there is duplication, obsolete material, and incorrect material.

Someone needs to take a look and decide what should happen to each doc, how they should be laid out and enumerate what work is needed so several of us can help do it.

@maryamariyan has volunteered to do this.

[jkotas]

From https://github.com/dotnet/runtime/pull/251#issuecomment-558385845:

docs\workflow\profiling talks about profiler API architecture (e.g. how one builds a CoreCLR profiler). It should not be under workflow.

[danmosemsft]

This would be a great place for folks to share other suggestions about those docs. Here's a list of all the markdown files, minus ones that are most obviously not affected by the consolidation and stand alone.

- [ ] CODE-OF-CONDUCT.md
- [ ] CONTRIBUTING.md
- [ ] README.md
- [ ] SECURITY.md

- [x] docs/area-owners.md
- [ ] docs/deep-dive-blog-posts.md
- [ ] docs/issues-pr-management.md
- [ ] docs/README.md

- [ ] docs/coding-guidelines/adding-api-guidelines.md
- [ ] docs/coding-guidelines/breaking-change-definitions.md
- [ ] docs/coding-guidelines/breaking-change-rules.md
- [ ] docs/coding-guidelines/breaking-changes.md
- [ ] docs/coding-guidelines/clr-code-guide.md
- [ ] docs/coding-guidelines/clr-jit-coding-conventions.md
- [ ] docs/coding-guidelines/coding-style.md
- [ ] docs/coding-guidelines/cross-platform-guidelines.md
- [ ] docs/coding-guidelines/cross-platform-performance-and-eventing.md
- [ ] docs/coding-guidelines/EventLogging.md
- [ ] docs/coding-guidelines/framework-design-guidelines-digest.md
- [ ] docs/coding-guidelines/interop-guidelines.md
- [ ] docs/coding-guidelines/interop-pinvokes.md
- [ ] docs/coding-guidelines/netstandard20-corefx-infra.md
- [ ] docs/coding-guidelines/package-projects.md
- [ ] docs/coding-guidelines/performance-guidelines.md
- [ ] docs/coding-guidelines/pinvoke-checker.md
- [ ] docs/coding-guidelines/project-guidelines.md
- [ ] docs/coding-guidelines/updating-ref-source.md
- [ ] docs/coding-guidelines/api-guidelines/nullability.md
- [ ] docs/coding-guidelines/api-guidelines/README.md
- [ ] docs/coding-guidelines/api-guidelines/System.Memory.md

- [ ] docs/project/analyzers.md
- [ ] docs/project/api-review-process.md
- [ ] docs/project/branching-guide.md
- [ ] docs/project/copyright.md
- [ ] docs/project/dogfooding.md
- [ ] docs/project/dotnet-filenames.md
- [ ] docs/project/dotnet-standards.md
- [ ] docs/project/garbage-collector-guidelines.md
- [ ] docs/project/glossary.md
- [ ] docs/project/how-to-track-changes.md
- [ ] docs/project/issue-guide.md
- [ ] docs/project/jit-testing.md
- [ ] docs/project/library-servicing.md
- [ ] docs/project/linux-performance-tracing.md
- [ ] docs/project/performance-guidelines.md
- [ ] docs/project/porting.md
- [ ] docs/project/profiling-api-status.md
- [ ] docs/project/public-signing.md
- [ ] docs/project/pull-request-policy.md
- [ ] docs/project/pullrequest-builds.md
- [ ] docs/project/repo-organization.md
- [ ] docs/project/strong-name-signing.md
- [ ] docs/project/support-dotnet-core-instructions.md
- [ ] docs/project/triage.md
- [ ] docs/project/updating-jitinterface.md
- [ ] docs/project/versioning.md
- [ ] docs/project/windows-performance-tracing.md
- [ ] docs/project/writing-tests.md
- [ ] docs/project/performance/JitOptimizerPlanningGuide.md
- [ ] docs/project/performance/JitOptimizerTodoAssessment.md

- [ ] docs/workflow/EditingAndDebugging.md
- [ ] docs/workflow/linux-requirements.md
- [ ] docs/workflow/macos-requirements.md
- [ ] docs/workflow/README.md
- [ ] docs/workflow/UsingDotNetCli.md
- [ ] docs/workflow/windows-requirements.md
- [ ] docs/workflow/building/coreclr/android.md
- [ ] docs/workflow/building/coreclr/cross-building.md
- [ ] docs/workflow/building/coreclr/crossgen.md
- [ ] docs/workflow/building/coreclr/freebsd-instructions.md
- [x ] docs/workflow/building/coreclr/linux-instructions.md
- [ ] docs/workflow/building/coreclr/osx-instructions.md
- [ ] docs/workflow/building/coreclr/REAMDE.md
- [ ] docs/workflow/building/libraries/code-coverage.md
- [ ] docs/workflow/building/libraries/cross-building.md
- [ ] docs/workflow/building/libraries/freebsd-instructions.md
- [ ] docs/workflow/building/libraries/netbsd-instructions.md
- [ ] docs/workflow/building/libraries/README.md

- [ ] docs/workflow/debugging/crash-dumps.md
- [ ] docs/workflow/debugging/debugging-instructions.md
- [ ] docs/workflow/debugging/debugging-packages.md
- [ ] docs/workflow/debugging/debugging-vscode.md
- [ ] docs/workflow/debugging/unix-instructions.md
- [ ] docs/workflow/debugging/windows-instructions.md

- [ ] docs/workflow/profiling/IL Rewriting Basics.md
- [ ] docs/workflow/profiling/Profiler Attach on CoreCLR.md
- [ ] docs/workflow/profiling/Profiler Breaking Changes.md
- [ ] docs/workflow/profiling/Profiler Loading.md
- [ ] docs/workflow/profiling/ReJIT on Attach.md

- [ ] docs/workflow/testing/AutomatedStressTestingForDiagnosticServer.md
- [ ] docs/workflow/testing/coreclr-testing.md
- [ ] docs/workflow/testing/filtering-tests.md
- [ ] docs/workflow/testing/libraries-testing.md
- [ ] docs/workflow/testing/Running-Tests-In-VisualStudio-IDE.md
- [ ] docs/workflow/testing/test-configuration.md
- [ ] docs/workflow/testing/unix-test-instructions.md
- [ ] docs/workflow/testing/UsingCoreRun.md
- [ ] docs/workflow/testing/UsingYourBuild.md
- [ ] docs/workflow/testing/viewing-jit-dumps.md
- [ ] docs/workflow/testing/windows-test-instructions.md

- [ ] src/coreclr/scripts/superpmi.md
- [ ] src/coreclr/src/debug/ee/amd64/gen_amd64InstrDecode/README.md
- [ ] src/coreclr/src/dlls/mscoree/coreclr/README.md
- [ ] src/coreclr/src/inc/readme.md
- [ ] src/coreclr/src/pal/src/libunwind/README.md
- [ ] src/coreclr/src/System.Private.CoreLib/Tools/GenUnicodeProp/Readme.md
- [ ] src/coreclr/src/ToolBox/SOS/SOS_README.md
- [ ] src/coreclr/src/tools/r2rdump/README.md
- [ ] src/coreclr/tests/src/Interop/ReadMe.md
- [ ] src/coreclr/tests/src/performance/Scenario/JitBench/unofficial_dotnet/README.md

- [ ] src/installer/managed/Microsoft.NET.HostModel/Bundle/README.md
- [ ] src/installer/test/scripts/linux-test/README.md

[jkotas]

src\libraries\SECURITY.md should be deleted. Redundant with SECURITY.md at the root.

[jkotas]

workflow described in docs\project\changing-corelib.md is not relevant for consolidated repo. This file should be deleted.

[ViktorHofer]

I removed a few files from the list like eng/common/REAMDE.md and the ones which were just deleted.

[danmosemsft]

https://github.com/dotnet/runtime/issues/253#issuecomment-558606619 suggests

Is there a directory tree doc outlining a brief description of whats what. I know that's not easy, but wondering if its been automated some how in docs? As after initial build the artifacts folder is quite daunting....

[tmds]

We can also improve for new contributors. There is no path from README that gets you to instructions that show how to build/test/... this repo.

[ViktorHofer]

There is a link to CONTRIBUTING.md which is the go-to place for such information: https://github.com/dotnet/runtime#how-can-i-contribute. We are probably missing links to the workflow docs from the CONTRIBUTING.md. Feel free to submit a PR to link to those. We still haven't cleaned up the docs.

[dhusemann]

@danmosemsft @ViktorHofer @maryamariyan Believe that all the links for Contributing.md have been updated. with #815. Is the workflow directory going to remain the same layout??

One thing I just noticed, with the delay of moving the Issues from the Coreclr and corefx repo's to runtime, that there will be a disconnect with finding the issues.

[danmosemsft]

I hit the same issue, contributing doesn't tell me HOW to contribute.

@maryamariyan any thoughts? i can help organize/move docs around, if you suggest what we need/ what should link where?

[dhusemann]

another question, some of the DOCS for building refer to repos that are going to be consolidated. Such as referring to dotnet/cli which has moved to dotnet/toolset which in turn will eventually be consolidated into dotnet/sdk.

Do ya'll want to wait for those repo's to fully consolidate before updating, or do an interim update as an example #881

[ViktorHofer]

an interim update as an example #881

An interim update sounds fine. We can a final update after the repos consolidate with a search&replace then.

[danmosemsft]

Is it reasonable to combine these? (append the latter to the former)? I always look for one and find the other -- or if I'm reading one I need the other.

- [ ] docs/coding-guidelines/interop-guidelines.md
- [ ] docs/coding-guidelines/interop-pinvokes.md