Add colour to PR Template and tweak CONTRIBUTING and README files

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,9 +5,9 @@
 
 ## Checklist:
 <!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
-<!--- Feel free to remove whole sections, not points within the sections, that do not apply -->
+<!--- Please remove whole sections, not points within the sections, that do not apply -->
 <!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
-- [ ] **I am associating a language with a new file extension.**
+- [ ] **I am adding a new extension to a language.**
   - [ ] The new extension is used in hundreds of repositories on GitHub.com
     - Search results for each extension:
       <!-- Replace FOOBAR with the new extension, and KEYWORDS with keywords unique to the language. Repeat for each extension added. -->
@@ -28,6 +28,9 @@
       - [URL to each sample source, if applicable]
     - Sample license(s):
   - [ ] I have included a syntax highlighting grammar: [URL to grammar repo]
+      <!-- Setting a color is only needed for 'programming' and 'markup' languages and will default to `#cccccc` if not specified. -->
+  - [ ] I have added a color: [Enter color in hex as `#123456` so the color can be seen in the PR body]
+    - I chose this color because: [Please specify why you chose this color. It helps in future if there is a request to change the color.]
   - [ ] I have updated the heuristics to distinguish my language from others using the same extension.
 
 - [ ] **I am fixing a misclassified language**

CONTRIBUTING.md

@@ -25,6 +25,7 @@ These components have their own dependencies - `icu4c`, and `cmake` and `pkg-con
 On macOS with [Homebrew](http://brew.sh/) the instructions below under Getting started will install these dependencies for you.
 
 On Ubuntu:
+
 ```bash
 apt-get install cmake pkg-config libicu-dev docker.io ruby ruby-dev zlib1g-dev build-essential libssl-dev
 ```
@@ -62,17 +63,19 @@ To add support for a new extension:
 1. Add at least one sample for your extension to the [samples directory][samples] in the correct subdirectory.
    We prefer examples of real-world code showing common usage.
    The more representative of the structure of the language, the better.
+
+   **"Hello world" examples will not be accepted.**
 1. Open a pull request, linking to a [GitHub search result][search-example] showing in-the-wild usage.
    If you are adding a sample, please state clearly the license covering the code.
    If possible, link to the original source of the sample.
    If you wrote the sample specifically for the PR and are happy for it to be included under the MIT license that covers Linguist, you can state this instead.
 
-Additionally, if this extension is already listed in [`languages.yml`][languages] and associated with another language, then sometimes a few more steps will need to be taken:
+Additionally, if this extension is already listed in [`languages.yml`][languages] and associated with another language, then a few more steps will need to be taken:
+
+1. Make sure that at least two example `.yourextension` files are present in the [samples directory][samples] for each language that uses `.yourextension`.
+1. If the two languages look vaguely similar, or one of the languages has uniquely identifiable characteristics, consider writing a [heuristic][] to help with the classification.
 
-1. Make sure that example `.yourextension` files are present in the [samples directory][samples] for each language that uses `.yourextension`.
-1. Test the performance of the Bayesian classifier with a relatively large number (1000s) of sample `.yourextension` files (ping **@lildude** to help with this).
-   This ensures we're not misclassifying files.
-1. If the Bayesian classifier does a bad job with the sample `.yourextension` files then a [heuristic][] may need to be written to help.
+Remember, the goal here is to try and avoid false positives!
 
 See [My Linguist PR has been merged but GitHub doesn't reflect my changes][merged-pr] for details on when your changes will appear on GitHub after your PR has been merged.
 
@@ -87,25 +90,30 @@ To add support for a new language:
 1. Add an entry for your language to [`languages.yml`][languages].
    Omit the `language_id` field for now.
 1. Add a syntax-highlighting grammar for your language using:
+
    ```bash
    script/add-grammar https://github.com/JaneSmith/MyGrammar
    ```
+
    This command will analyze the grammar and, if no problems are found, add it to the repository.
    If problems are found, please report them to the grammar maintainer as you will otherwise be unable to add it.
+
    **Please only add grammars that have [one of these licenses][licenses].**
 1. Add samples for your language to the [samples directory][samples] in the correct subdirectory.
+   We prefer examples of real-world code showing common usage.
+   The more representative of the structure of the language, the better.
+
+   **"Hello world" examples will not be accepted.**
 1. Generate a unique ID for your language by running `script/update-ids`.
 1. Open a pull request, linking to [GitHub search results][search-example] showing in-the-wild usage.
    Please state clearly the license covering the code in the samples.
    Link directly to the original source if possible.
    If you wrote the sample specifically for the PR and are happy for it to be included under the MIT license that covers Linguist, you can state this instead.
 
-In addition, if your new language defines an extension that's already listed in [`languages.yml`][languages] (such as `.foo`) then sometimes a few more steps will need to be taken:
+In addition, if your new language defines an extension that is already listed in [`languages.yml`][languages] and associated with another language, then a few more steps will need to be taken:
 
-1. Make sure that example `.foo` files are present in the [samples directory][samples] for each language that uses `.foo`.
-1. Test the performance of the Bayesian classifier with a relatively large number (1000s) of sample `.foo` files (ping **@lildude** to help with this).
-   This ensures we're not misclassifying files.
-1. If the Bayesian classifier does a bad job with the sample `.foo` files, then a [heuristic][] may need to be written to help.
+1. Make sure that at least two example `.foo` files are present in the [samples directory][samples] for each language that uses `.foo`.
+1. If the two languages look vaguely similar, or one of the languages has uniquely identifiable characteristics, consider writing a [heuristic][] to help with the classification.
 
 Remember, the goal here is to try and avoid false positives!
 
@@ -119,7 +127,6 @@ This process can help differentiate between, for example, `.h` files which could
 
 Misclassifications can often be solved by either adding a new filename or extension for the language or adding more [samples][] to make the classifier smarter.
 
-
 ## Fixing syntax highlighting
 
 Syntax highlighting in GitHub is performed using TextMate-compatible grammars.
@@ -198,23 +205,18 @@ Here's our current build status: [![Actions Status](https://github.com/github/li
 Linguist is maintained with :heart: by:
 
 - **@Alhadis**
-- **@larsbrinkhoff**
 - **@lildude** (GitHub staff)
-- **@pchaigno**
 
 As Linguist is a production dependency for GitHub we have a couple of workflow restrictions:
 
 - Anyone with commit rights can merge Pull Requests provided that there is a :+1: from a GitHub staff member.
 - Releases are performed by GitHub staff so we can ensure GitHub.com always stays up to date with the latest release of Linguist and there are no regressions in production.
 
-
 [grammars]: /vendor/README.md
 [heuristic]: https://github.com/github/linguist/blob/master/lib/linguist/heuristics.yml
 [languages]: /lib/linguist/languages.yml
 [licenses]: https://github.com/github/linguist/blob/9b1023ed5d308cb3363a882531dea1e272b59977/vendor/licenses/config.yml#L4-L15
-[new-issue]: https://github.com/github/linguist/issues/new
 [samples]: /samples
 [search-example]: https://github.com/search?utf8=%E2%9C%93&q=extension%3Aboot+NOT+nothack&type=Code&ref=searchresults
-[gpr]: https://docs.github.com/packages/using-github-packages-with-your-projects-ecosystem/configuring-rubygems-for-use-with-github-packages
 [#5756]: https://github.com/github/linguist/issues/5756
 [merged-pr]: /docs/troubleshooting.md#my-linguist-pr-has-been-merged-but-gitHub-doesnt-reflect-my-changes

README.md

@@ -2,9 +2,6 @@
 
 [![Actions Status](https://github.com/github/linguist/workflows/Run%20Tests/badge.svg)](https://github.com/github/linguist/actions)
 
-[issues]: https://github.com/github/linguist/issues
-[new-issue]: https://github.com/github/linguist/issues/new
-
 This library is used on GitHub.com to detect blob languages, ignore binary or vendored files, suppress generated files in diffs, and generate language breakdown graphs.
 
 ## Documentation
@@ -30,6 +27,7 @@ Accordingly, we highly recommend you install a version of Ruby using Homebrew, `
 
 Linguist uses [`charlock_holmes`](https://github.com/brianmario/charlock_holmes) for character encoding and [`rugged`](https://github.com/libgit2/rugged) for libgit2 bindings for Ruby.
 These components have their own dependencies.
+
 1. charlock_holmes
     * cmake
     * pkg-config
@@ -95,6 +93,7 @@ $ github-linguist
 #### Additional options
 
 ##### `--rev REV`
+
 The `--rev REV` flag will change the git revision being analyzed to any [gitrevisions(1)](https://git-scm.com/docs/gitrevisions#_specifying_revisions) compatible revision you specify.
 
 This is useful to analyze the makeup of a repo as of a certain tag, or in a certain branch.
@@ -118,12 +117,14 @@ $ github-linguist jekyll
 ```
 
 And here is Jekyll's published website, from the gh-pages branch inside their repository.
+
 ```console
 $ github-linguist jekyll --rev origin/gh-pages
 100.00% 2568354    HTML
 ```
 
 ##### `--breakdown`
+
 The `--breakdown` or `-b` flag will additionally show the breakdown of files by language.
 
 You can try running `github-linguist` on the root directory in this repository itself:
@@ -149,6 +150,7 @@ lib/linguist.rb
 ```
 
 ##### `--json`
+
 The `--json` or `-j` flag output the data into JSON format.
 
 ```console
@@ -157,6 +159,7 @@ $ github-linguist --json
 ```
 
 This option can be used in conjunction with `--breakdown` to get a full list of files along with the size and percentage data.
+
 ```console
 $ github-linguist --breakdown --json
 {"Dockerfile":{"size":1212,"percentage":"0.31","files":["Dockerfile","tools/grammars/Dockerfile"]},"Ruby":{"size":264519,"percentage":"66.84","files":["Gemfile","Rakefile","bin/git-linguist","bin/github-linguist","ext/linguist/extconf.rb","github-linguist.gemspec","lib/linguist.rb",...]}}
@@ -213,7 +216,6 @@ lib/linguist.rb
 
 Please check out our [contributing guidelines](CONTRIBUTING.md).
 
-
 ## License
 
 The language grammars included in this gem are covered by their repositories' respective licenses.