Update docs to be new-contributor friendly

[karelz]

Our repo docs are not super-friendly to new contributors. It would be nice to improve them.

[karelz]

EDIT: All the content was migrated to CoreFX main page and to CoreFX wiki for easier collaboration.

I started the work on 2016/12: https://github.com/karelz/corefx/tree/docs, but didn't have time to finish it.

Here's dump of my original plan:

.NET Core

• Releases: https://github.com/dotnet/core/tree/master/release-notes
• Road map - https://github.com/dotnet/core/blob/master/roadmap.md
• How to use (with VS, VS Code, command-line) - https://github.com/dotnet/core/#get-started
• Deploying apps - https://docs.microsoft.com/en-us/dotnet/articles/core/preview3/deploying/
• .NET documentation - https://docs.microsoft.com/en-us/dotnet/

Issues

• Issue guide
  • Issue areas - https://github.com/dotnet/core/
  • Setup lives in CLI repo (not core-setup)
• API review process
  • Adding APIs is hard: HashCode: https://twitter.com/terrajobst/status/799428189386747904

Contributions
Use parts of first-time Roslyn contribution blog post - part1 and part2

• QUERY is:issue is:open label:up-for-grabs no:assignee -label:api-needs-work
  • TODO: Point to label:easy
  • TODO: Point to "add tests" issues
• Enlist + GitHub usage + Prereqs
  • sync.cmd
  • uCRT: https://docs.microsoft.com/en-us/dotnet/articles/core/windows-prerequisites
  • GitHub usage help (MS): http://aka.ms/GitHelp
• Small change
  • What kind of changes - LINK
    • up for grabs / wishlist / 2.0.0 / simple - https://github.com/dotnet/corefx/issues/15663#issuecomment-276732806
    • Add:
      • Decisions to take / reject changes: https://github.com/dotnet/corefx/issues/6351#issuecomment-267779077
      • Breaking changes: List<T>.GetEnumerator.Current should throw InvalidOperationException after elements was added to list coreclr#8415 (comment)
        • Note: Was tweeted: https://twitter.com/matthewwarren/status/805711973467955200
  • How to build - build.cmd
  • How to run tests
    • How to debug test failure
      • msbuild /t:test /p:testdebugger=devenv.exe
      • msbuild /t:test /p:testdebugger=c:\debuggers\windbg.exe
    • How to rerun specific test
    • How to run Outerloop tets
  • How to submit PR
    • General rules (titles, what kind of changes, don't mix changes, coding style)
    • @dotnet-bot docs
• Expose API in CoreFX
  • Note: http://aka.ms/api-review LINK is used in file licenses
  • Add it for netcore20 (latest)
  • How to add tests
• Expose API across CoreCLR/CoreFX
  • Where to put tests
  • How to run tests
  • Exposing API: Type.IsSZArray property. corefx#16996 (Reflection.Emit)
  • Magic: (JanK) S.M.Span<T>: Add Clear()/Fill(T value) corefx#14396 (comment)
• Advanced changes
  • Expose API only on Windows/Linux -- use Registry example?
  • Documentation changes
  • Desktop tests
  • Perf tests
    • https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/performance-tests.md
    • How to add them: Add Performance Tests from the CLR Perf Lab corefx#7152

Random useful

• How to debug (VS, VS Code, windbg)
  • Mixed mode
  • Linux
  • Mac
• How to investigate perf
  • Production level profiling (e.g. needed in 100% CPU load #19429)
  • Memory analysis (GC happens too often) (e.g. needed in UDP Socket using SocketAsyncEventArgs garbage collects nearly every second #19481)
  • https://github.com/dotnet/BenchmarkDotNet
  • Perf Analysis on .NET Core on Windows - Vance's blog post
  • Collecting perf data on .NET Core on Linux - Vance's blog post
• How trace Runtime event
  • On Windows - PerfView, on Linux
• How to change .NET Core docs
  • Tutorials, samples - https://github.com/dotnet/docs
  • API reference - same (should light up in ~April)
  • MS Only: .NET Core website - https://github.com/dotnet/dotnet-core-website
• TryRoslyn: http://tryroslyn.azurewebsites.net/
• How to port .NET Framework app to .NET Core:
  • https://docs.microsoft.com/en-us/dotnet/articles/core/porting/
  • http://developerblog.redhat.com/2016/12/08/observations-porting-from-net-framework-to-net-core/
• Developing .NET Core apps: https://blogs.msdn.microsoft.com/mvpawardprogram/2016/07/19/key-steps-in-developing-net-core-applications/
• Using reference source from here is OK: https://github.com/Microsoft/referencesource (same license)
  • Richard's explanation: https://github.com/dotnet/coreclr/issues/9301#issuecomment-277534312
• Useful tips and tricks, tools, education material - https://github.com/quozd/awesome-dotnet (we might bring some links to CoreFX docs)

Any help to move this forward is welcome!
cc @danmosemsft @mellinoe

[karelz]

Great blog post from first-time contributor in Roslyn @MaximRouiller to leverage:

• Part1: https://blog.decayingcode.com/post/contributing-to-open-source-my-first-roslyn-pull-request-getting-the-environment-ready/
• Part2: https://blog.decayingcode.com/post/contributing-to-open-source-my-first-roslyn-pull-request-fixing-the-bug/

[karelz]

Adding some recent new contributors, who might have either suggestions/opinions on the topic, or they might benefit from the draft, or maybe even might be interested in helping out crafting the docs for their future selfs ;-)

@WinCPP @nbarbettini @Pothulapati

[karelz]

Also for everyone interested -- check out dotnet/corefx#17619 about current plans and where help is needed most these days (you don't have to restrict to that of course).

[karelz]

Added another good start for new contributors: query with "add new tests" issues

[MaximRouiller]

Wow... thank you @karelz. Didn't know that my two small blog posts would trigger an avalanche of actionable items. 😮

[karelz]

@MaximRouiller as you see, I had these docs planned since December - I just didn't have time to execute on it yet :( ... too many fire drills, too much repo shepherding and also the somewhat emberassing fact that I didn't yet contribute a real fix into CoreFX in my time on the team since last October, so it would cost me quite a bit of time to collect all the info - clearly I need help :)

Your blog posts fit into it nicely and I want to leverage your writeups. They were the right nudge I needed to push the docs and 'easy'-queries a little bit further right now instead of in couple of months :) ... it is also easier to invest into things when there are immediate customers/dogfooders/contributors who can provide feedback and who benefit from your work right away ;).

So thank you for the nudge and your interest! Any help or suggestions from first-time contributors will be appreciated.

cc @sharwell

[MaximRouiller]

@karelz Apparently, I'm good at nudging since that prompted @sharwell in FINALLY updating his StackOverflow profile. 😉

I'm ready to take on another bug/improvement/issue. Doesn't need to be Roslyn only. If the same process I applied to Roslyn can be done for corefx or any other repository, I'll gladly do a write-up on my experience in contributing to a particular repository.

The only thing to remember is that I didn't contribute to any main repository before (yay! (?)) so I'm a real first-time contributor to any repository you might throw at me.

So... like they say at poker. Hit me. 😄

[karelz]

@MaximRouiller challenge accepted. It would be great to see similar blog post (or comparison) on CoreFX repo -- you can start with easy issues and use draft of the docs above.

BTW: I am myself 'newbie' in contributions to CoreFX as well. I actually didn't submit any PR beside docs changes since I joined CoreFX team in 2016/10 (although I did plenty of code changes to the CLR code base over my 12 years on the team from which I sent 7 years as individual contributor i.e. "real dev").
That's why I think I am also uniquely positioned to write good newbie contributor docs :) (moreover git version control system is also new to me, so I understand that transition pain as well :))

[karelz]

I have moved the skeleton of my plan above to CoreFX wiki. Every GH user has RW permissions, so we all can collaborate on the docs fast (without PRs review delay, etc.).

I have also merged my main page updates from December (mentioned above) to master. Main CoreFX page is now updated and links directly to the wiki, encouraging contributions to the docs.

I hope this will make it easier for everyone. Closing this issue as everyone can now directly make changes ...

[karelz]

FYI: For easier collaboration I have created a new gitter room: https://gitter.im/dotnet/corefx-contrib-docs also linked from https://github.com/dotnet/corefx/wiki/New-contributor-Docs