Merge pull request #4682 from pnp:contribution-updates

Updated contribution guidelines and PR template

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,13 +4,11 @@
 
 > To submit a pull request with multiple authors, make sure that at least one commit is a co-authored commit by adding a `Co-authored-by:` trailer to the commit's message. E.g.: `Co-authored-by: name <name@example.com>`
 
-> Put an `x` in all the items that apply (`[x]`, without spaces), make notes next to any that haven't been addressed.
+> Put an `x` in all the items that apply (`[x]`, no spaces between the `[`, the `x`, and the `]` ), make notes next to any that haven't been addressed.
 
-- [ ] Bug fix?
-- [ ] New sample?
+- [ ] New sample
+- [ ] Bug fix/update
 - [ ] Related issues: fixes #X, partially #Y, mentioned in #Z
-- [ ] Needs API permissions?
-- [ ] Has other prerequisites? (E.g. requires a list, document library, etc.)
 
 
 ## What's in this Pull Request?
@@ -26,16 +24,16 @@ Node version used:
 
 ## Checklist
 
-> This checklist is mostly useful as a reminder of small things that can easily be forgotten – it is meant as a helpful tool rather than hoops to jump through.
+> This checklist is used to automatically pre-process your pull request; It is meant to help process pull requests in a timely manner, rather than hoops to jump through.
 > 
-> Put an `x` in all the items that apply ([x], no spaces), make notes next to any that haven't been addressed.
-
+> Put an `x` in all the items that apply (`[x]`, no spaces between the `[`, the `x`, and the `]` ). Make notes next to any that haven't been addressed.
 
 - [ ] My pull request affects only ONE sample.
 - [ ] My sample does not build with any warnings
-- [ ] I have updated the README file.
-- [ ] My README has at least one static high-resolution screenshot (i.e. not a GIF)
-- [ ] My README contains complete setup instructions, including pre-requisites and permissions required
+- [ ] I have updated the `README.md` file's **Version history**. For new samples, created a new `README.md` file matching [this template](templates/README-template.md)
+- [ ] My `README.md` has at least one static high-resolution screenshot (i.e. not a GIF) located in the `assets` folder.
+- [ ] My `README.md` contains complete setup instructions, including pre-requisites and permissions required
+- [ ] My solution includes a `.nvmrc` file indicating the version of Node.js
 
 ## Submitter Guidance (DELETE AFTER READING)
 > 

.github/PULL_REQUEST_TEMPLATE/bug-fix.md

@@ -1,27 +0,0 @@
-> By submitting this pull request, you agree to the [contribution guidelines](https://github.com/pnp/sp-dev-fx-webparts/blob/main/CONTRIBUTING.md)
-
-> If you aren't familiar with how to contribute to open-source repositories using GitHub, or if you find the instructions on this page confusing, [sign up](https://forms.office.com/Pages/ResponsePage.aspx?id=KtIy2vgLW0SOgZbwvQuRaXDXyCl9DkBHq4A2OG7uLpdUREZVRDVYUUJLT1VNRDM4SjhGMlpUNzBORy4u) for one of our [Sharing is Caring](https://pnp.github.io/sharing-is-caring/#pnp-sic-events) events. It's completely free, and we'll guide you through the process.
-
-|        Q        |                    A                    |
-| --------------- | --------------------------------------- |
-| Bug fix?        | yes                               |
-| Related issues? | fixes #X, partially #Y, mentioned in #Z |
-
-## What's in this Pull Request?
-
-> Please describe the changes in this PR. Sample description or details around bugs which are being fixed.
-> 
-> _(DELETE THIS PARAGRAPH AFTER READING)_
-
-## Submitter Guidance (DELETE AFTER READING)
-> 
-> *Please update this PR information accordingly. We'll use this as part of our release notes in monthly communications.*
->
-> *Pull requests that do not follow this template will be automatically rejected.*
-> 
-> *Please target your PR to `main` branch.*
->
-> *Remember that this repository is maintained by community members who volunteer their time to help. Be courteous and patient.*
-> _(DELETE THIS SECTION AFTER READING)_
-
-

CONTRIBUTING.md

@@ -17,6 +17,7 @@ If you have questions about how to use SharePoint Framework or any of the provid
 
 * [SharePoint Developer Space](http://aka.ms/SPPnP-Community) at http://techcommunity.microsoft.com
 * [SharePoint Stack Exchange](http://sharepoint.stackexchange.com/) with 'spfx' tag
+* Use our [Discord channel](https://discord.gg/HeAgMk8Y)
 
 ## Typos, Issues, Bugs and contributions
 
@@ -38,7 +39,10 @@ When you submit a new sample, please follow these guidelines:
     - Your solution's source code
     - An `assets` folder, containing screenshots
     - A `README.md` file
+    - A '.nvmrc` file
 * You must only submit samples for which you have the rights to share. Make sure that you asked for permission from your employer and/or clients before committing the code to an open-source repository, because once you submit a pull request, the information is public and _cannot be removed_.
+* If your sample is a SharePoint Framework Extensions, please consider adding it to the [sp-dev-fx-extensions](https://github.com/pnp/sp-dev-fx-extensions) repository instead
+* If your sample is an Adaptive Card Extension (ACE), consider adding it to the [sp-dev-fx-aces](https://github.com/pnp/sp-dev-fx-aces) repository instead.
 
 ### Sample Folder
 
@@ -59,24 +63,23 @@ When you submit a new sample, please follow these guidelines:
 * You will need to have a `README.md` file for your contribution, which is based on [the provided template](../main/templates/README-template.md) under the `samples` folder. Please copy this template to your project and update it accordingly. Your `README.md` must be named exactly `README.md` -- with capital letters -- as this is the information we use to make your sample public.
 * You will need to have a screenshot picture of your sample in action in the `README.md` file ("pics or it didn't happen"). The preview image must be located in the `assets` folder in the root of your sample folder.
     * All screen shots must be located in the `assets` folder. Do not point to your own repository or any other external source
-* The README template contains a specific tracking image at the end of the file with an `img` element pointing to `https://pnptelemetry.azurewebsites.net/sp-dev-fx-webparts/samples/YOUR-SOLUTION-NAME`. This is a transparent image which is used to track how many visits each sample receives in GitHub.
-* Update the image `src` attribute according with the repository name and folder information. For example, if your sample is named `react-todo` in the `samples` folder, you should update the `src` attribute to `https://pnptelemetry.azurewebsites.net/sp-dev-fx-webparts/samples/react-todo`
+
+> **NOTE:** It is called a "web part", not a "webpart". "WebPart" relates to the class.
+
+#### Visitor stats image
+
+* The README template contains a specific tracking image at the end of the file with an `img` element pointing to `https://m365-visitor-stats.azurewebsites.net/sp-dev-fx-webparts/samples/YOUR-SOLUTION-NAME`. This is a transparent image which is used to track how many visits each sample receives in GitHub.
+* Update the image `src` attribute according with the repository name and folder information. For example, if your sample is named `react-todo` in the `samples` folder, you should update the `src` attribute to `https://m365-visitor-stats.azurewebsites.net/sp-dev-fx-webparts/samples/react-todo`
   * Update the image `src` attribute according with the repository name and folder information.
-* If you find an existing sample which is similar to yours, please extend the existing one rather than submitting a new similar sample
-  * When you update existing samples, please update also `README.md` file accordingly with information on provided changes and with your author details
-* Make sure to document each function in the `README.md`
-* If you include your social media information under **Authors** in the **Solution** section, we'll use this information to promote your contribution on social media, blog posts, and community calls.
-    * Try to use the following syntax:
-    ```md
-    folder name | Author Name ([@yourtwitterhandle](https://twitter.com/yourtwitterhandle))
-    ```
-* If you include your company name after your name, we'll try to include your company name in blog posts and community calls.
-    * Try to use the following syntax:
-    ```md
-    folder name | Author Name ([@yourtwitterhandle](https://twitter.com/yourtwitterhandle)), Company Name
-    ```
-* For multiple authors, please provide one line per author
+
+#### Contributors
+
+* Make sure to list yourself as a contributor by adding a bullet to the **Contributors** list.
+  * You should only point to your GitHub profile. If you want to provide your social media, employer, etc., please do so in your GitHub profile so it stays up-to-date in the future.
+  * We'll override your contributor link when we process the pull request, so save yourself the trouble.
 * If you prefer to not use social media or disclose your name, we'll still accept your sample, but we'll assume that you don't want us to promote your contribution on social media.
+* For multiple authors, please provide one line per author
+  > If you want all authors to be eligible for a badge through the [Community Recognition Program](https://pnp.github.io/recognitionprogram/), make sure to add `Co-authored-by:` in your commit message. For more information, please refer to GitHub's instruction on [Creating a commit with multiple authors](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors)
 
 ### Assets
 
@@ -86,6 +89,29 @@ When you submit a new sample, please follow these guidelines:
 * You can add as many screen shots as you'd like to help users understand your sample without having to download it and install it.
 * You can include animated images (such as `.gif` files), but you must provide at least one static `.png` file
     * There is no need to include the steps where you find your web part and add it to a page. Just get to the good stuff!
+* Screen shot images must be located in the `assets` folder. We cannot accept links to images located outside of the repository.
+
+> **NOTE:** We will not process pull requests for new samples without a screen shot
+
+### .nvmrc
+
+Each version of SPFx supports only a limited number of Node.js versions. To help others use your sample, please provide a `.nvmrc` file in the root of your solution.
+
+* Create a new file with the name `.nvmrc` (including the dot at the beginning of the file name).
+* Open the .`nvmrc` file in a text editor and specify the desired Node.js version. The version should be in the format `vMajor.Minor.Patch`. For example, if you want to use Node.js version 14.17.0, simply write `v14.17.0` in the file. Make sure there are no leading or trailing spaces in the file.
+* Save the .nvmrc file in the root directory of your project.
+
+> To generate this file automatically, you can use the following command:
+>
+>  ```shell
+>  node -v > .nvmrc
+>  ```
+>
+> If you use Windows, your automatically-generated `.nvmrc` may include invisible characters that may cause issues. To be sure, you can run the following command in PowerShell once your `.nvmrc` file is generated:
+> 
+> ```powershell
+> [string]::Join( "`n", (gc .nvmrc)) | sc .nvmrc 
+> ```
 
 ## Submitting Pull Requests
 
@@ -121,7 +147,7 @@ Before you submit your pull request consider the following guidelines:
 * Make your changes in a new git branch:
 
   ```shell
-  git checkout -b react-taxonomypicker main
+  git checkout -b your-sample-name main
   ```
 
 * Ensure your fork is updated and not behind the upstream **sp-dev-fx-webparts** repo. Refer to these resources for more information on syncing your repo: