Improve experience for new contributors to repo

[mkArtakMSFT]

Summary

The ASP.NET Core repo can be difficult to get started with for new contributors. We should make improvements to the repo setup and documentation to support new contributors on-boarding to the project.

Motivation and goals

Our build setup has a few gaps that make it difficult to get started for the wider contributor community:

• Some aspects of the setup are opinionated about using Visual Studio
• Some aspects of the build (e.g. Selenium tests) only work on Windows
• Diagnosing build failures can be difficult for a repo of this size
• Some contributors have trouble understanding our test quarantine process

In scope

• Make it easy for users to contribute to a single part of the repo (e.g. SignalR or Blazor)
• Reduce the likelihood that users will run into issues depending on their OS/editor
• Reduce the time from clone to successfully making a change
• Investigate integrating our repo with CodeSpaces on VS/VS Code

Out of scope

• Improving build performance
• Complete rehaul of our current repo infrastructure

People involved

@captainsafia, @Tratcher, @shirhatti, @wtgodbe, @dougbu

timheuer may be a person to get relevant information from regarding Codespaces bit here.

[ghost]

Thanks for contacting us.
We're moving this issue to the Next sprint planning milestone for future evaluation / consideration. We will evaluate the request when we are planning the work for the next milestone. To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[captainsafia]

Below are the notes from the working group meeting on 11/5/2020.

Known Issues

• Some aspects of the setup are opinionated about using Visual Studio
• Some aspects of the build (e.g. Selenium tests) only work on Windows
• Diagnosing build failures can be difficult for a repo of this size
• Some contributors have trouble understanding our test quarantine process
• People tend to build the entire repo when they want to contribute to a single section of it
  • We don't do this in our own developer workflows
  • Understandable because this is what we document in the BuildFromSource.md
• Repo requires a lot of dependencies in order to build
  • E.g. you cannot even build without having VS Preview installed
    • A little bit out of our control
  • Java, Node, Yarn, Selenium, VS, etc.
• Dependency checker seems to have regressed
  • Doesn't work as well as it used to (maybe not all)
  • Some of the defaults have been changed to build native and the build seems to fail for those
• README is general for the entire repo as opposed to for specific areas (Blazor, MVC, Templates, etc) and associated templates
• Lack of CTI tests for specific scenarios
  • We currently have a CTI tests for building/debugging on VS for Windows
• IISExpress samples in the repo don't work because they rely on a native component that hasn't been built
  • MVC and Blazor samples don't work when run with IIS Express
  • No guidance we currently can give to users to get samples working with IIS Express
• Users get confused when the CI build complains about things unrelated to their PR and how to address them
• Users are tempted to use the top-level build.cmd to build the entire repo

Quick Wins

• Add repo area specific documentation (Add README for each project in repo #27561)
• Update CONTRIBUTING.md docs to explain our CI process, how to address common feedback from the CI, and how we review PRs (Update CONTRIBUTING.md for project #27562)
  • dotnet/runtime's Contributor: https://github.com/dotnet/runtime/blob/master/CONTRIBUTING.md
• Change default server for samples from IIS Express to Kestrel
  • Might be masking the real issue here
• Refine CTI tests for building and setting up repo
  • Make sure that CTI scenarios cover as clean a scenario as possible
  • CTI is at capacity for some intervals but we have some flexibility for less frequent checks
  • Might get more capacity after FY21 when Razor Tooling tests will be moved to different CTI
• Create a launch.json for VS Code for tests and sample apps on the repo (Improve repo development experience on VS Code and VS4Mac #27260)
• Create git hooks to autoformat user code via dotnet format (Add git pre-commit hooks for applying formatting to source #27632)
  • Use editorconfig from dotnet/runtime project?
  • Investigate: does dotnet format read from the editorconfig?
• Take build.cmd out of the root and incentivize users to use build.cmd in each project (Remove top-level build scripts in favor of area-specific build scripts #27631)
  • Prompt user if they actually want to run the top-level build.cmd instead of the area specific ones
  • Update the docs as well
• Need to make sure that all areas have a build.cmd
  • Also make sure that all areas have a build.sh

Ambitious Investigations

• Dynamically acquire dependencies the same way we do via dotnet (Dynamically acquire dependencies needed for each project #27633)
  • Only install the dependency when you're building projects that need them
• Get the repo working on Codespaces/Nexus/cloud environment
• Move away from Selenium (more cross-platform solution)
• Investigate ways to trim down the number of projects in the repo
  • THERE ARE FOUR PROJECTS!
• Investigate ways to split up the build within the repo Improve experience for working with individual projects in the monorepo #27634
  • Might be hard to do with restricted resources available in the CI
  • Runtime's split build approach is expensive from a repo perspective
• (Optional) Containerizing each project area
  • Dockerfile for each project area

[Pilchie]

Had to miss a meeting today, but one pattern I see is that a lot of people want to start with a tag of a servicing build, make a change and then consume it in their own apps so that they can verify it fixes an issue.

This is currently difficult for a few reasons. At least:

1. Many servicing builds are built internally and have authenticated feeds in NuGet.config that need to be removed.
2. It isn't clear how to set versions and such so that you can produce a build that is easy to consume from an existing project.

Anyone have ideas about how to make those issues easier to deal with?

I know 1. is a bit hard, because we want to tag the actual commit that produced the build, which means we can't remove those NuGet feeds. I think some of the SDK repos used to actually tag twice though- once for the actual build, and once that was the same in spirit but with internal references updated to public ones after we ship. Maybe we should consider something like that?

[dougbu]

@Pilchie at some point, Core-Eng was talking about marking the -int feeds as disabled by default but I'm not sure what came of that. @wtgodbe what's the current story❔

[wtgodbe]

at some point, Core-Eng was talking about marking the -int feeds as disabled by default but I'm not sure what came of that. @wtgodbe what's the current story?

I'm not sure where we're at with this, @mmitche do you know?

[mmitche]

That should be happening today.

The darc-int feeds should show up in the disablePackageSources section of NuGet.config, and the dnceng internal project builds remove those entries when setting up the restore operations.

[dougbu]

@captainsafia what work remains here❔ If none, please close. If any, please add the details.

In the meantime, adding to the DoI board…

[captainsafia]

@dougbu We're using this is a theme task. We've got most of the relevant stuff tracked in individual items. I think the plan is to generally keep these items open until the work is complete.

[dougbu]

I'm not sure what milestone is appropriate for still-in-progress themes and cleared the milestone for now. Suggestions @adityamandaleeka @rafikiassumani-msft @mkArtakMSFT @Pilchie❔ Or, are we done on this from your perspective @captainsafia❔

[captainsafia]

@dougbu We're not done but we are tracking a lot of this stuff with smaller issues in the DoI board: https://github.com/orgs/dotnet/projects/15

Specifically this issue: #27609

So, I think we can close this in favor of that one since it has concrete work items outlined.