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

Add README for each project in repo #27561

Open
19 of 30 tasks
captainsafia opened this issue Nov 5, 2020 · 8 comments
Open
19 of 30 tasks

Add README for each project in repo #27561

captainsafia opened this issue Nov 5, 2020 · 8 comments
Labels
affected-medium This issue impacts approximately half of our customers area-infrastructure Includes: MSBuild projects/targets, build scripts, CI, Installers and shared framework Docs This issue tracks updating documentation enhancement This issue represents an ask for new feature or an enhancement to an existing one severity-major This label is used by an internal tool
Milestone

Comments

@captainsafia
Copy link
Member

captainsafia commented Nov 5, 2020

Part of #27380.

Let's improve the project-specific docs in the repo. For larger projects (Blazor, MVC, SignalR) the docs should contain information about the project's dependency, test setup, an overview of the folder structure, etc. For smaller projects, the doc should contain a description of the contents and what they might be useful for.

Below is a sample README to use when populating each project so the repo is consistent.

# ProjectName

A brief description of the project area here. In applicable, include a link to the `docs.microsoft.com` page associated with this area.

## Description

An overview of the source files within the project, a general overview of the design, and other information helpful to get the general idea of the implementation. For full-fledged areas like SignalR or Blazor, this should be a paragraph or a few sentences with some bullets.

## Development Setup

### Build

Provide a description of any dependencies that are needed to run the project, helpful flags that users can use when invoking the `build.cmd` command, and any other project-specific build instructions that would aid users during dev.

If applicable, include this standard statement at the end to point users to the top-level instructions for building each project from source.

To build this specific project from source, follow the instructions [on building the project](../../docs/BuildFromSource.md#step-3-build-the-repo).

### Test

A guide on how to run the tests for the project, including any dependencies that are needed to run the tests,

Include any information about specific customizations made to the tests for this project area (e.g. TestServer in Components project).

If applicable, include this standard statement at the end to point users to top-level instructions.

To run the tests for this project, [run the tests on the command line](../../docs/BuildFromSource.md#running-tests-on-command-line) in this directory.

## More Information

For more information, see the [ASP.NET Core README](../../README.md).
@captainsafia captainsafia added Docs This issue tracks updating documentation area-infrastructure Includes: MSBuild projects/targets, build scripts, CI, Installers and shared framework labels Nov 5, 2020
@Tratcher Tratcher self-assigned this Nov 9, 2020
@blowdart
Copy link
Contributor

blowdart commented Nov 9, 2020

I really wish you would keep the standard security text in the parent readme in each readme as well. If you're overriding all of this it's important to highlight the right way to report security bugs.

@JamesNK
Copy link
Member

JamesNK commented Nov 9, 2020

Rather than copy parts of the main readme, we should add a link to it. e.g.

## More Information

For more information, see the [ASP.NET Core README](../README.md).

@captainsafia
Copy link
Member Author

@JamesNK Good idea. I've updated the template in the issue with this.

@dougbu
Copy link
Member

dougbu commented Nov 9, 2020

SiteExtensions (@dougbu)

@jkotalik I have mucked in that area a few times but don't really get how the extensions are used. Could you take that README too or find another victim delegate❔

@jkotalik
Copy link
Contributor

jkotalik commented Nov 9, 2020

I can try.

@captainsafia
Copy link
Member Author

Hi folks! Adjusted the template based on some feedback from Pranav. To avoid repeatedly stating that users can run the build.cmd command in the directory, we'll instead refer to the "build subset of code" section in the top-level docs so we have less duplication there. We should still include any project-specific build instructions like helpful flags to pass to the build command or dependencies that need to be installed.

Ditto for the test section.

@wtgodbe wtgodbe added affected-medium This issue impacts approximately half of our customers enhancement This issue represents an ask for new feature or an enhancement to an existing one severity-major This label is used by an internal tool labels Nov 12, 2020 — with ASP.NET Core Issue Ranking
@halter73
Copy link
Member

I don't think we should worry about duplicating small inline sample commands like those in https://github.com/dotnet/aspnetcore/blob/45d77afa717e26576c28ee97d3638ce25532d0ed/src/SignalR/README.md. Having to click links to see what the one-line build and test commands are is annoying. Linking to the top-level docs is great, but deduping stuff like one-line build and test commands should be a non-goal in my opinion.

@Rick-Anderson
Copy link
Contributor

Feel free to mention me for an edit review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
affected-medium This issue impacts approximately half of our customers area-infrastructure Includes: MSBuild projects/targets, build scripts, CI, Installers and shared framework Docs This issue tracks updating documentation enhancement This issue represents an ask for new feature or an enhancement to an existing one severity-major This label is used by an internal tool
Projects
None yet
Development

No branches or pull requests

17 participants