Docs | Update Contributing Documentation (#3065)

MichelZ · web-flow · commit 1998216e8781 · 2024-12-09T14:45:28.000-08:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,13 +7,14 @@ General contribution guidance is included in this document. Additional guidance
 
 ## Up for Grabs
 
-The team marks the most straightforward issues as "up for grabs". This set of issues is the place to start if you are interested in contributing but new to the codebase.
+The team marks the most straightforward issues as "up for grabs" and issues that are well suited to get you started as "Good first issue". This set of issues is the place to start if you are interested in contributing but new to the codebase.
 
-- [dotnet/sqlclient - "up for grabs"](https://github.com/dotnet/sqlclient/labels/Up-for-Grabs)
+- [dotnet/sqlclient - :raised_hands: Up-for-Grabs](https://github.com/dotnet/sqlclient/labels/%3Araised_hands%3A%20Up-for-Grabs)
+- [dotnet/sqlclient - :sparkles: Good first issue](https://github.com/dotnet/sqlclient/labels/%3Asparkles%3A%20Good%20first%20issue)
 
 ## Contribution "Bar"
 
-Project maintainers will merge changes that improve the product significantly and broadly and that align with the [Microsoft.Data.SqlClient roadmap](https://github.com/dotnet/sqlclient/blob/master/roadmap.md).
+Project maintainers will merge changes that improve the product significantly and broadly and that align with the [Microsoft.Data.SqlClient roadmap](roadmap.md).
 
 Contributions must also satisfy the other published guidelines defined in this document.
 
@@ -42,19 +43,21 @@ Please do not:
 
 ## Using Labels
 
-We encourage adding appropriate labels to issues and pull requests to allow filtering and analysis effectively. The below variables are required for new Pull Requests if applicable:
+As adding labels [is not possible](https://stackoverflow.com/questions/13829466/how-to-put-a-label-on-an-issue-in-github-if-you-are-not-a-contributor-owner/13829505#13829505) for contributors, please comment in the issue and pull request on what labels should be added.
+The below variables are required for new Pull Requests if applicable:
 
 | Label | Description |
 | ----- | ----------- |
-| [Public API](https://github.com/dotnet/SqlClient/labels/Public%20API) | Use this variable if a new Public API is added to the Pull Request.
-| [Breaking Change](https://github.com/dotnet/SqlClient/labels/Breaking%20Change) | Use this variable if the Pull Request breaks an existing API. |
-| [Backport to CoreFx](https://github.com/dotnet/SqlClient/labels/Backport%20to%20CoreFx) | Use this variable if the Issue/Pull Request needs to be backported to System.Data.SqlClient in [dotnet/corefx](https://github.com/dotnet/corefx) |
-| [Managed SNI](https://github.com/dotnet/SqlClient/labels/Managed%20SNI) | Use this label if the issue/PR relates to issues in Managed SNI |
-| [Tests](https://github.com/dotnet/SqlClient/labels/Tests) | Use this label for pull requests that add only tests to the repository. |
+| [:new: Public API](https://github.com/dotnet/SqlClient/labels/%3Anew%3A%20Public%20API) | Use this variable if a new Public API is added to the Pull Request.
+| [:hammer: Breaking Change](https://github.com/dotnet/SqlClient/labels/%3Ahammer%3A%20Breaking%20Change) | Use this variable if the Pull Request breaks an existing API. |
+| [Area\Managed SNI](https://github.com/dotnet/SqlClient/labels/Area%5cManaged%20SNI) | Use this label if the issue/PR relates to issues in Managed SNI |
+| [Area\Tests](https://github.com/dotnet/SqlClient/labels/Area%5cTests) | Use this label for pull requests that add only tests to the repository. |
+
+You can find all possible labels [here](https://github.com/dotnet/SqlClient/labels)
 
 ## Reporting security issues and security bugs
 
-Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) [secure@microsoft.com](mailto:secure@microsoft.com). You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://technet.microsoft.com/en-us/security/ff852094.aspx).
+Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) [secure@microsoft.com](mailto:secure@microsoft.com). You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [MSRC FAQ](https://www.microsoft.com/en-us/msrc/faqs-report-an-issue?rtc=1&oneroute=true).
 
 ## File Headers
 
@@ -70,7 +73,7 @@ The following file header is used for Microsoft.Data.SqlClient. Please use it fo
 
 You must sign a [.NET Foundation Contribution License Agreement (CLA)](https://cla.dotnetfoundation.org) before your PR will be merged. This is a one-time requirement for projects in the .NET Foundation. You can read more about [Contribution License Agreements (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia.
 
-The agreement: [net-foundation-contribution-license-agreement.pdf](https://github.com/dotnet/home/blob/master/guidance/net-foundation-contribution-license-agreement.pdf)
+The agreement: [contribution-license-agreement.pdf](https://cla.dotnetfoundation.org)
 
 You don't have to do this up-front. You can simply clone, fork, and submit your pull-request as usual. When your pull-request is created, it is classified by a CLA bot. If the change is trivial (for example, you just fixed a typo), then the PR is labelled with `cla-not-required`. Otherwise it's classified as `cla-required`. Once you signed a CLA, the current and all future pull-requests will be labelled as `cla-signed`.
 
diff --git a/COPYRIGHT.md b/COPYRIGHT.md
@@ -6,4 +6,4 @@
 
 ## Binary License
 
-- **Microsoft.Data.SqlClient** binary distributions (nuget packages) are licensed as MIT (identical to the [Microsoft.Data.SqlClient source license](https://github.com/dotnet/sqlclient/blob/master/LICENSE)).
+- **Microsoft.Data.SqlClient** binary distributions (NuGet packages) are licensed as MIT (identical to the [Microsoft.Data.SqlClient source license](LICENSE)).
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/dotnet/sqlclient/master/LICENSE)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
 [![Nuget](https://img.shields.io/nuget/dt/Microsoft.Data.SqlClient?label=Nuget.org%20Downloads&style=flat-square&color=blue)](https://www.nuget.org/packages/Microsoft.Data.SqlClient)
 [![Build status](https://sqlclientdrivers.visualstudio.com/public/_apis/build/status/ADO/CI-SqlClient)](https://sqlclientdrivers.visualstudio.com/public/_build/latest?definitionId=1879)
 
@@ -108,7 +108,7 @@ Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https:
 
 ## License
 
-The Microsoft.Data.SqlClient Driver for SQL Server is licensed under the MIT license. See the [LICENSE](https://github.com/dotnet/SqlClient/blob/master/LICENSE) file for more details.
+The Microsoft.Data.SqlClient Driver for SQL Server is licensed under the MIT license. See the [LICENSE](LICENSE) file for more details.
 
 ## Trademarks
 
diff --git a/contributing-workflow.md b/contributing-workflow.md
@@ -10,30 +10,31 @@ We use and recommend the following workflow:
     - You can skip this step for trivial changes.
     - Reuse an existing issue on the topic, if there is one.
     - Get agreement from the team and the community that your proposed change is a good one.
-    - If your requested change needs a new public API, add a Label "**Public API**" to your issue.
-    - If your requested change address performance improvement in the driver, add a Label "**Performance**" to your issue.
-    - For any other improvements in the driver, add a Label "**Enhancement**" to your issue.
+    - Suggest [Labels](CONTRIBUTING.md#using-labels) to add for your issue.
     - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.
 2. Create a personal fork of the repository on GitHub (if you don't already have one).
-3. Create a branch off of master (`git checkout -b mybranch`).
+3. Create a branch off of main (`git checkout -b mybranch`).
     - Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue.
     - Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
 4. Make and commit your changes.
-    - Please follow our [Commit Messages](contributing.md#commit-messages) guidance.
+    - Please follow our guidance [here](CONTRIBUTING.md#dos-and-donts).
 5. Add new tests corresponding to your change, if nor present and applicable.
 6. Build the repository with your changes.
     - Make sure that the builds are clean.
     - Make sure that the tests are all passing, including your new tests.
-7. Create a pull request (PR) against the upstream repository's **master** branch.
+7. Create a pull request (PR) against the upstream repository's **main** branch.
     - Push your changes to your fork on GitHub (if you haven't already).
+    - Create a PR to the **main** branch
+    - Describe the changes that you have done in the PR
+    - Suggest [Labels](CONTRIBUTING.md#using-labels) to add to the PR in the description
 
 > Note: It is OK for your PR to include a large number of commits. Once your change is accepted, you will be asked to squash your commits into one or some appropriately small number of commits before your PR is merged.
 
 > Note: It is OK to create your PR as "[WIP]" on the upstream repo before the implementation is done. This can be useful if you'd like to start the feedback process concurrent with your implementation. State that this is the case in the initial PR comment.
 
 ## PR - CI Process
 
-The [SqlClient Continuous Integration](https://dev.azure.com/sqlclientdrivers-ci/sqlclient/) (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean.
+The [SqlClient Continuous Integration](https://dev.azure.com/sqlclientdrivers/public/_build) (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean.
 
 If the CI build fails for any reason, the PR issue will be updated with a link that can be used to determine the cause of the failure.
 
@@ -50,64 +51,3 @@ Use ["Squash and Merge"](https://github.com/blog/2141-squash-your-commits) by de
 Do so, even if the PR contains only one commit. It creates a simpler history than "Create a Merge Commit". Reasons that PR authors may request "Merge and Commit" may include (but are not limited to):
   - The change is easier to understand as a series of focused commits. Each commit in the series must be buildable so as not to break `git bisect`.
   - Contributor is using an e-mail address other than the primary GitHub address and wants that preserved in the history. Contributor must be willing to squash the commits manually before acceptance.
-
-## PR Verification and Validation
-
-For testing PR changes and ensure they work fine, we maintain a public feed that lists NuGet Packages built with merged commits.
-
-**Link to Public Feed:** [Microsoft.Data.SqlClient.Commits](https://pkgs.dev.azure.com/sqlclientdrivers-ci/sqlclient/_packaging/Microsoft.Data.SqlClient.Commits/nuget/v3/index.json)
-
-**Add this feed to NuGet Sources**
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<configuration>
-  <packageSources>
-    <clear />
-    <add key="Microsoft.Data.SqlClient.Commits" value="https://pkgs.dev.azure.com/sqlclientdrivers-ci/sqlclient/_packaging/Microsoft.Data.SqlClient.Commits/nuget/v3/index.json" />
-  </packageSources>
-</configuration>
-```
-OR
-```cmd
-nuget.exe sources Add -Name "Microsoft.Data.SqlClient.Commits" -Source "https://pkgs.dev.azure.com/sqlclientdrivers-ci/sqlclient/_packaging/Microsoft.Data.SqlClient.Commits/nuget/v3/index.json"
-```
-
-### Pushing to Public Feed
-
-Maintainers of [dotnet/sqlclient](https://github.com/dotnet/SqlClient) manually push NuGet Packages to this feed after the PR is merged to the `master` branch and a commit ID has been generated on `master`.
-
-Not every commit is built and published on the public CI feed, but only the commits that make considerable difference to the driver will be uploaded in this feed.
-
-The label **Push to Commit Feed** will be added to the Pull Request if it is pushed to the feed.
-
-### Downloading Packages
-
-The package naming conventions follow SemVer 2.0.0 and also provide changeset information to ensure the right PR changes are being downloaded for testing:
-
-Package names will be like: `Microsoft.Data.SqlClient.1.1.0-build.19250.1-c21aa7c.nupkg`
-
-Breaking down:
-- `1.1.0-build` - Identifier for currently active driver version in Build.
-- `19250.1` - Unique identifier to keep latest PRs on top of the feed.
-- `c21aa7c` - Short Commit Id to identify merged commit in `master`.
-
-> Note: This public feed is only for testing and validating new PR changes. Packages from feed will be eventually removed when the maximum NuGet Package limit of **50** is reached. We do not recommend using packages from this feed in client applications.
-
-## Nightly builds
-
-We also maintain NuGet feed for Nightly builds that are generated when new changes are merged in the repository. To access Nightly builds, add below configuration to package sources:
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<configuration>
-  <packageSources>
-    <clear />
-    <add key="Microsoft.Data.SqlClient.dev" value="https://pkgs.dev.azure.com/sqlclientdrivers-ci/sqlclient/_packaging/Microsoft.Data.SqlClient.dev/nuget/v3/index.json" />
-  </packageSources>
-</configuration>
-```
-OR
-```cmd
-nuget.exe sources Add -Name "Microsoft.Data.SqlClient.dev" -Source "https://pkgs.dev.azure.com/sqlclientdrivers-ci/sqlclient/_packaging/Microsoft.Data.SqlClient.dev/nuget/v3/index.json"
-```
diff --git a/roadmap.md b/roadmap.md
@@ -4,26 +4,15 @@ The Microsoft.Data.SqlClient roadmap communicates project priorities for evolvin
 
 ## Released Versions
 
-- [Release Notes](https://github.com/dotnet/sqlclient/blob/master/release-notes/README.md) - For detailed release notes summarizing of all changes/features released.
+- [Release Notes](release-notes/README.md) - For detailed release notes summarizing of all changes/features released.
 - [GitHub Releases](https://github.com/dotnet/sqlclient/releases) - For downloading NuGet Packages and identifying driver releases with changelog notes.
 
 ## Upcoming Ship Dates
 
-| Milestone                 | Release Date | Project Board |
-|---------------------------|--------------|---------------|
-| Microsoft.Data.SqlClient v1.1 (servicing) | As needed (see also [1.1 releases](https://github.com/dotnet/sqlclient/blob/master/release-notes/1.1)) | Closed |
-| Microsoft.Data.SqlClient v2.1 (servicing) | As needed (see also [2.1 releases](https://github.com/dotnet/sqlclient/blob/master/release-notes/2.1)) | Closed |
-| Microsoft.Data.SqlClient v3.0 (servicing) | As needed (see also [3.0 releases](https://github.com/dotnet/sqlclient/blob/master/release-notes/3.0)) | Closed |
-| Microsoft.Data.SqlClient v4.0 (servicing) | As needed (see also [4.0 releases](https://github.com/dotnet/sqlclient/blob/master/release-notes/4.0)) | Closed |
-| Microsoft.Data.SqlClient v4.1 (servicing) | As needed (see also [4.1 releases](https://github.com/dotnet/sqlclient/blob/master/release-notes/4.1)) | Closed |
-| Microsoft.Data.SqlClient v5.0 | GA (General Availability) estimated for May 2022 | [SqlClient 5.0.0](https://github.com/dotnet/SqlClient/projects/9)
-
-> Note: Dates are calendar year (as opposed to fiscal year).
+For upcoming release dates, see [SqlClient milestones](https://github.com/dotnet/SqlClient/milestones).
 
 [SqlClient Projects](https://github.com/dotnet/SqlClient/projects) are used by our development team to define roadmap of prioritized work. SqlClient Boards contain issues, pull requests, and other features, development activities that are categorized as cards. Our goal is to be transparent over priorities, work in progress and deliverables.
 
-Milestone information is also available for GitHub Issues and Pull Requests [dotnet/sqlclient milestones](https://github.com/dotnet/sqlclient/milestones).
-
 ## Feedback
 
 The best way to give feedback is to create issues in the [dotnet/sqlclient](https://github.com/dotnet/sqlclient) repo.

Original file line number	Diff line number	Diff line change
`@@ -6,4 +6,4 @@`
`6`	`6`
`7`	`7`	`## Binary License`
`8`	`8`
`9`		`-- Microsoft.Data.SqlClient binary distributions (nuget packages) are licensed as MIT (identical to the [Microsoft.Data.SqlClient source license](https://github.com/dotnet/sqlclient/blob/master/LICENSE)).`
	`9`	`+- Microsoft.Data.SqlClient binary distributions (NuGet packages) are licensed as MIT (identical to the [Microsoft.Data.SqlClient source license](LICENSE)).`