diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 66e1afd77ef..2a3df928486 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,6 +1,149 @@ -Contributing -====== +# How to contribute -Information on contributing to this repo is in the [Contributing Guide](https://github.com/aspnet/Home/blob/master/CONTRIBUTING.md) in the AspNetCore repo. +We welcome community pull requests for bug fixes, enhancements, and documentation. Code and API documentation are in this repo. Conceptual documentation is in the [EntityFramework.Docs](https://github.com/dotnet/EntityFramework.Docs) repo. -To build this repo, follow specific instructions on [getting and building the code](../docs/getting-and-building-the-code.md). +For code changes, you will need to [fork and clone the repo and build the code locally](./docs/getting-and-building-the-code.md). + +## Choosing an issue + +All contributions should address an [open issue](https://github.com/dotnet/efcore/issues) in the [dotnet/efcore](https://github.com/dotnet/efcore) repo. + +### Bugs verses enhancements + +Issues are typically labeled with [type-enhancement](https://github.com/dotnet/efcore/issues?q=is%3Aopen+is%3Aissue+label%3Atype-enhancement) or [type-bug](https://github.com/dotnet/efcore/issues?q=is%3Aopen+is%3Aissue+label%3Atype-bug). + +* Bugs are places where EF Core is doing something that it was not designed to. +* Enhancements are suggestions to improve EF Core by changing existing or adding new functionality. + +Bugs are usually relatively small, self-contained changes. However, this does not necessarily make them easy to work on, since finding the root cause and fixing it without breaking any other functionality can be tricky. + +Enhancements can be anything from tiny changes to support a variation on an existing scenario, to massive cross-cutting features that will take many months to implement. The bigger the enchantment, the more important it is to communicate with the EF Team before working on a contribution. + +### Good first issues + +Most issues are available to be tackled by the community, even if not explicitly labeled as such. However, two labels are specifically about community contributions: + +* Issues that we believe are relatively straightforward to implement are labeled with [good-first-issue](https://github.com/dotnet/efcore/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). These are good candidates for community pull requests. +* Issues labeled with [help-wanted](https://github.com/dotnet/efcore/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) indicate that the issue requires some specialist expertise to implement. If you have expertise in the relevant area, then working on these issues can be of great help to the EF team. Note that these issues **are not typically easy to implement**. + +Issues labeled with [needs-design](https://github.com/dotnet/efcore/issues?q=is%3Aopen+is%3Aissue+label%3Aneeds-design) indicate that the EF Core team has not solidified on an approach to tackle the issue. This typically makes the issue much more difficult for the community to implement. + +### Create an issue + +If there is no existing issue tracking the change you want to make, then [create one](https://github.com/dotnet/efcore/issues/new/choose)! PRs that don't get merged are often those that are created without any prior discussion with the team. An issue is the best place to have that discussion, ideally before the PR is submitted. + +### Fixing typos + +An issue is not required for simple non-code changes like fixing a typo in documentation. In fact, these changes can often be submitted as a PR directly from the browser, avoiding the need to fork and clone. + +## Workflow + +The typical workflow for contributing to EF Core is outlined below. This is not a set-in-stone process, but rather guidelines to help ensure a quality PR that we can merge efficiently. + +* [Set up your development environment](./docs/getting-and-building-the-code.md) so that you can build and test the code. Don't forget to [create a fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) for your work. +* Make sure all tests are passing. (This is typically done by running `test` at a command prompt.) +* Choose an issue (see above), understand it, and **comment on the issue** indicating what you intend to do fix it. **This communication with the team is very important and often helps avoid throwing away lots of work caused by taking the wrong approach.** +* Create and checkout a [branch](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository) in your local clone. You will use this branch to prepare your PR. +* Make appropriate code and test changes. Follow the patterns and code style that you see in the existing code. Make sure to add tests that fail without the change and then pass with the change. +* Consider other scenarios where your change may have an impact and add more testing. It's difficult to add too many tests. +* When you are done with changes, make sure _all_ existing tests are still passing. (Again, typically by running `test` at a command prompt.) +* Commit changes to your branch and push the branch to your GitHub fork. +* Go to the main [EF Core repo](https://github.com/dotnet/efcore/pulls) and you should see a yellow box suggesting you create a PR from your fork. Do this, or [create the PR by some other mechanism](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests). +* Sign the [contributor license agreement](https://cla.dotnetfoundation.org/) if you have not already done so. +* Wait for the feedback from the team and for the continuous integration (C.I.) checks to pass. +* Add and push new commits to your branch to address any issues. + +The PR will be merged by a member of the EF Team once the C.I. checks have passed and the code has been approved. + +## Breaking changes + +EF Core is used by many thousands of existing applications. We want to make it as easy as possible for those existing applications to update to new versions. A change that causes an existing application to break when being updated is known as a "breaking change". Sometimes it is necessary to make a breaking change to keep the platform alive and moving forward. However, each such breaking change must be explicitly called out and will only be approved if the value of making the change greatly outweighs the pain of breaking existing applications. + +### API breaking changes + +The easiest type of breaking change to identify are those that change the public API surface such that existing code no longer works. API breaks come in two forms: + +* Source breaking changes happen when existing code fails to compile against the new public API surface. +* Binary breaking changes happen when an assembly compiled against an older version of EF Core fails to work when run with a new version of EF Core. + +For example, consider the following class: + +```C# +public class Foo +{ + public Foo(string a) + { + A = a; + } + + public string A { get; } +} +``` +Assuming we shipped this, and now want to add a new parameter to the constructor: + +```C# +public class Foo +{ + public Foo(string a, string b) + { + A = a; + B = b; + } + + public string A { get; } + public string B { get; } +} +``` + +This is both a source breaking change and a binary breaking change. The single parameter constructor is gone, so existing assemblies cannot bind to it, and existing source code cannot compile against it. + +What if instead we made the new parameter optional? + +```C# +public class Foo +{ + public Foo(string a, string b = null) + { + A = a; + B = b; + } + + public string A { get; } + public string B { get; } +} +``` + +Now this is a binary breaking change, but _not_ a source breaking change. Source that previously compiled against the single parameter constructor can still compile against the new two-parameter constructor. However, assemblies attempting to bind to the single parameter constructor will still not find it. + +Binary breaking changes, especially for database providers, can have lower impact and may be acceptable. However, where possible try to write code that is not breaking at all. For example, in this case by adding a new constructor overload: + +```C# +public class Foo +{ + public Foo(string a) + : this(a, null) + { + } + + public Foo(string a, string b) + { + A = a; + B = b; + } + + public string A { get; } + public string B { get; } +} +``` + +This is now neither a source nor a binary breaking change. + +### Behavioral breaking changes + +Behavioral breaking changes happen when the behavior of calling some API changes without the API itself changing. For example, if calling `DbContext.Add` previously resulted in an entity in the `Added` state, and now results in it being in the `Modified` state, then that's a behavioral break. Existing applications will not be expecting a `Modified` entity and may therefore not behave correctly. + +Behavioral breaking changes are hard to identify and are one of the reasons testing is so important. Running all the existing tests can help find behavioral breaks. Likewise, implementing good tests with your change helps ensure any future breaks will be discovered. + +## Code-of-conduct + +Please remember to abide by our [code-of-conduct](.github/CODE_OF_CONDUCT.md) while working on contributions. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 744a91ee89a..2d77d260b26 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -9,10 +9,7 @@ Please check if the PR fulfills these requirements Fixes #bugnumber - [ ] Tests for the changes have been added (for bug fixes / features) -- [ ] Code meets the expectations our engineering guidelines. - https://github.com/dotnet/aspnetcore/wiki/Engineering-guidelines +- [ ] Code follows the same patterns and style as existing code in this repo -Review the guidelines for CONTRIBUTING.md for more details. +Review the guidelines for [contributing](./.github/CONTRIBUTING.md) for more details. --> - - diff --git a/README.md b/README.md index c13305581af..a4e1119c8bd 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -Repository -========== +# Repository [![build status](https://img.shields.io/azure-devops/build/dnceng/public/51/main)](https://dev.azure.com/dnceng/public/_build?definitionId=51) [![test results](https://img.shields.io/azure-devops/tests/dnceng/public/51/main)](https://dev.azure.com/dnceng/public/_build?definitionId=51) @@ -8,8 +7,7 @@ This repository is home to the following [.NET Foundation](https://dotnetfoundat * [Entity Framework Core](#entity-framework-core) * [Microsoft.Data.Sqlite](#microsoftdatasqlite) -Entity Framework Core --------------------- +## Entity Framework Core [![latest version](https://img.shields.io/nuget/v/Microsoft.EntityFrameworkCore)](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore) [![preview version](https://img.shields.io/nuget/vpre/Microsoft.EntityFrameworkCore)](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore/absoluteLatest) [![downloads](https://img.shields.io/nuget/dt/Microsoft.EntityFrameworkCore)](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore) @@ -31,7 +29,7 @@ Use the `--version` option to specify a [preview version](https://www.nuget.org/ We recommend using the [daily builds](docs/DailyBuilds.md) to get the latest code and provide feedback on EF Core. These builds contain latest features and bug fixes; previews and official releases lag significantly behind. -### Usage +### Basic usage The following code demonstrates basic usage of EF Core. For a full tutorial configuring the `DbContext`, defining the model, and creating the database, see [getting started](https://docs.microsoft.com/ef/core/get-started/) in the docs. @@ -63,8 +61,19 @@ using (var db = new BloggingContext()) } ``` -Microsoft.Data.Sqlite --------------------- +### Build from source + +Most people use EF Core by installing pre-build NuGet packages, as shown above. Alternately, [the code can be built and packages can be created directly on your development machine](./docs/getting-and-building-the-code.md). + +### Contributing + +We welcome community pull requests for bug fixes, enhancements, and documentation. See [How to contribute](./.github/CONTRIBUTING.md) for more information. + +### Getting support + +If you have a specific question about using these projects, we encourage you to [ask it on Stack Overflow](https://stackoverflow.com/questions/tagged/entity-framework-core*?tab=Votes). If you encounter a bug or would like to request a feature, [submit an issue](https://github.com/dotnet/efcore/issues/new/choose). For more details, see [getting support](.github/SUPPORT.md). + +## Microsoft.Data.Sqlite [![latest version](https://img.shields.io/nuget/v/Microsoft.Data.Sqlite)](https://www.nuget.org/packages/Microsoft.Data.Sqlite) [![preview version](https://img.shields.io/nuget/vpre/Microsoft.Data.Sqlite)](https://www.nuget.org/packages/Microsoft.Data.Sqlite/absoluteLatest) [![downloads](https://img.shields.io/nuget/dt/Microsoft.Data.Sqlite.Core)](https://www.nuget.org/packages/Microsoft.Data.Sqlite) @@ -84,7 +93,7 @@ Use the `--version` option to specify a [preview version](https://www.nuget.org/ We recommend using the [daily builds](docs/DailyBuilds.md) to get the latest code and provide feedback on Microsoft.Data.Sqlite. These builds contain latest features and bug fixes; previews and official releases lag significantly behind. -### Usage +### Basic usage This library implements the common [ADO.NET](https://docs.microsoft.com/dotnet/framework/data/adonet/) abstractions for connections, commands, data readers, and so on. For more information, see [Microsoft.Data.Sqlite](https://docs.microsoft.com/dotnet/standard/data/sqlite/) on Microsoft Docs. @@ -106,18 +115,19 @@ using (var connection = new SqliteConnection("Data Source=Blogs.db")) } ``` -Getting support ---------------- +### Build from source -If you have a specific question about using these projects, we encourage you to [ask it on Stack Overflow](https://stackoverflow.com/questions/tagged/entity-framework-core*?tab=Votes). If you encounter a bug or would like to request a feature, [submit an issue](https://github.com/dotnet/efcore/issues/new/choose). For more details, see [getting support](.github/SUPPORT.md). +Most people use Microsoft.Data.Sqlite by installing pre-build NuGet packages, as shown above. Alternately, [the code can be built and packages can be created directly on your development machine](./docs/getting-and-building-the-code.md). + +### Contributing + +We welcome community pull requests for bug fixes, enhancements, and documentation. See [How to contribute](./.github/CONTRIBUTING.md) for more information. -Contributing ------------- +### Getting support -If you're interested in contributing to these projects, see [contributing](.github/CONTRIBUTING.md). +If you have a specific question about using these projects, we encourage you to [ask it on Stack Overflow](https://stackoverflow.com/questions/tagged/microsoft.data.sqlite). If you encounter a bug or would like to request a feature, [submit an issue](https://github.com/dotnet/efcore/issues/new/choose). For more details, see [getting support](.github/SUPPORT.md). -See also --------- +## See also * [Documentation](https://docs.microsoft.com/ef/core/) * [Roadmap](https://docs.microsoft.com/ef/core/what-is-new/roadmap) diff --git a/docs/getting-and-building-the-code.md b/docs/getting-and-building-the-code.md index eefa53be89b..d9d9baf62bb 100644 --- a/docs/getting-and-building-the-code.md +++ b/docs/getting-and-building-the-code.md @@ -1,22 +1,41 @@ # Main branch -Following instructions are for current **main** branch only. For building release/2.x branches go to [Earlier versions](https://github.com/dotnet/efcore/wiki/Getting-and-Building-the-Code#earlier-versions). +The following instructions are for current **main** branch only. For building release/2.x branches go to [Earlier versions](https://github.com/dotnet/efcore/wiki/Getting-and-Building-the-Code#earlier-versions). ## Prerequisites -EF Core does not generally need any prerequisites installed to build the code. However, the SQL Server tests require that SQL Server LocalDb be installed. For this, and for a rich developer experience, install [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) 16.8.0 preview2 or higher version with the "ASP.NET and web development" workload. +EF Core does not generally need any prerequisites installed to build the code. However, running tests requires certain local databases to be available: + +* The SQL Server tests require a local SQL Server installation. This can be: + * SQL Server LocalDb, usually obtained by installing the latest [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) public preview with the "ASP.NET and web development" workload selected. + * SQL Server [Express or Developer Edition](https://www.microsoft.com/en-us/sql-server/sql-server-downloads). When not using LocalDb, make sure to set the environment variable `Test__SqlServer__DefaultConnection` to the connection string that EF Core tests should use. +* The Cosmos tests require that the [Azure Cosmos Emulator](https://docs.microsoft.com/azure/cosmos-db/local-emulator-release-notes) is installed. Use the default installation options. Make sure to re-start the emulator each time you restart your machine. + * The Cosmos tests are optional and will be skipped if the emulator is not available. If you are not making Cosmos changes, then you may choose to skip installing the emulator and let the continuous integration system handle Cosmos testing. + * Tip: Turn off "Rate Limiting" in the emulator to make the Cosmos tests run faster. + +![Switch off Cosmos Rate Limiting](rate_limiting.png) + +## Fork the repository + +If you plan to [contribute changes back to EF Core](./.github/CONTRIBUTING.md), then first [create a fork of the EFCore repo on GitHub](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo). ## Clone the repository -Using your favorite [git](http://git-scm.com/) client, clone the repository. +Using your favorite [git](http://git-scm.com/) client, clone the repository. For example, to clone the main repo: ```console git clone https://github.com/dotnet/efcore.git ``` +Or if you have created a fork called `efcore` in your personal GitHub: + +```console +git clone https://github.com/myusername/efcore.git +``` + ## Build -To build the code just call build[.cmd/.sh]. This will install preview SDK as needed, restore packages, and build all projects. This does not run tests. +To build the code just call build[.cmd/.sh]. This is an **important step** since it will install a preview .NET SDK alongside EF Core. This ensures EF Core is being built with the expected SDK and msbuild version. Running `build` also restores packages and builds all projects. Tests are not run. ```console build @@ -33,7 +52,7 @@ The `build` script has different arguments to perform specific actions. The full ## Using Visual Studio -**Important** The command line `build` (see above) must be run before using the solution with Visual Studio. +**The command line `build` (see above) must be run before using the solution with Visual Studio.** The build script installs a preview .NET Core SDK. In order to make sure Visual studio (or any other IDE) is using same SDK, certain environment variables need to be set. To configure your local environment and open solution file in Visual Studio, run following command: @@ -54,6 +73,12 @@ Tests can be run on the command line (after build) by running `test`: test ``` +### Solving common build errors + +1. Check that the package source URLs listed in the Nuget.config file in the root of the repository are accessible. +2. Clean the source directory. `git clean -xid` will clean files in the EF source directory. +3. Clear nuget packages and caches. `nuget.exe locals all -clear` will delete the NuGet caches. (You can get nuget.exe from or use `dotnet nuget`). + *** # Earlier versions (2.x or older) @@ -117,7 +142,7 @@ $env:PATH="$env:USERPROFILE/.dotnet/x64;"+$env:PATH ### Solving common build errors 1. Check that the package source URLs listed in the Nuget.config file in the root of the repository are accessible. -2. Clean the source directory. `git clean -xid` will clean files in the EF source directory. +2. Clean the source directory. `git clean -xid` will clean files in the EF source directory. 3. Clear nuget packages and caches. `nuget.exe locals all -clear` will delete the NuGet caches. (You can get nuget.exe from or use `dotnet nuget`). 4. Reinstall .NET Core CLI. Our build script automatically installs a version to `%USERPROFILE%\.dotnet`. diff --git a/docs/rate_limiting.png b/docs/rate_limiting.png new file mode 100644 index 00000000000..8259de42884 Binary files /dev/null and b/docs/rate_limiting.png differ