doc: updates per @anthonyharrison's feedback

Author: terriko

.github/workflows/pythonapp.yml

@@ -24,12 +24,12 @@ jobs:
       - name: Install pre-commit
         run: |
           python -m pip install --upgrade pip
+          python -m pip install --upgrade setuptools wheel
           python -m pip install --upgrade pre-commit
           pre-commit install
       - name: Install cve-bin-tool if needed
         if: ${{ matrix.tool == 'format_checkers' }}
         run: |
-          python -m pip install --upgrade setuptools wheel
           python -m pip install .
       - name: Run ${{ matrix.tool }}
         run: |

CONTRIBUTING.md

@@ -19,6 +19,8 @@ If you've already contributed to other open source projects, contributing to the
     - [Running black by itself](#running-black-by-itself)
     - [Other linting tools](#other-linting-tools)
   - [Making a new branch & pull request](#making-a-new-branch--pull-request)
+    - [Commit message tips](#commit-message-tips)
+    - [Sharing your code with us](#sharing-your-code-with-us)
     - [Checklist for a great pull request](#checklist-for-a-great-pull-request)
   - [Code Review](#code-review)
   - [Style Guide for cve-bin-tool](#style-guide-for-cve-bin-tool)
@@ -78,7 +80,7 @@ Replace MYUSERNAME with your own GitHub username.
 
 This section isn't required, but many contributors find it helpful, especially for running tests using different versions of python.
 
-[virtualenv](https://virtualenv.pypa.io/en/latest/) is a tool for setting up virtual python environments.  This allows you to have all the dependencies for cve-binary-tool set up in a single environment, or have different environments set up for testing using different versions of Python.  
+[virtualenv](https://virtualenv.pypa.io/en/latest/) is a tool for setting up virtual python environments.  This allows you to have all the dependencies for cve-bin-tool set up in a single environment, or have different environments set up for testing using different versions of Python.
 
 To install it:
 
@@ -128,7 +130,7 @@ If you want to run a local copy of cve-bin-tool, the recommended way is to insta
 python3 -m pip install --user -e .
 ```
 
-Then you can type `cve-binary-tool` on the command line and it will do the right thing.  This includes some special code intended to deal with adding new checkers to the list on the fly so things should work seamlessly for you while you're building new contributions.
+Then you can type `cve-bin-tool` on the command line and it will do the right thing.  This includes some special code intended to deal with adding new checkers to the list on the fly so things should work seamlessly for you while you're building new contributions.
 
 ### Help, my checkers aren't loading
 
@@ -157,6 +159,7 @@ CVE Binary Tool uses a few tools to improve code quality and readability:
 - `isort` sorts imports alphabetically and by type
 - `black` provides automatic style formatting.  This will give you basic [PEP8](https://www.python.org/dev/peps/pep-0008/) compliance. (PEP8 is where the default python style guide is defined.)
 - `flake8` provides additional code "linting" for more complex errors like unused imports.
+- `pyupgrade` helps us be forward compatible with new versions of python.
 
 We provide a `dev-requirements.txt` file which includes all the precise versions of tools as they'll be used in GitHub Actions.  You an install them all using pip:
 
@@ -207,8 +210,14 @@ specify a whole folder using ```./```
 
 As well as `black` for automatically making sure code adheres to the style guide, we use `flake8` to help us find things like unused imports.  The [flake8 documentation](https://flake8.pycqa.org/en/latest/user/index.html) covers what you need to know about running it.
 
+We use [pyupgrade](https://github.com/asottile/pyupgrade) to make sure our syntax is updated to fit new versions of python.
+
 We also have a spell checker set up to help us avoid typos in documentation.  The [spelling actions readme file](https://github.com/intel/cve-bin-tool/tree/main/.github/actions/spelling) gives more information including how to add new words to the dictionary if needed.
 
+We also have a tool to help make sure that new checkers are added to the tables in our documentation.  [The format_checkers code is here](https://github.com/intel/cve-bin-tool/blob/main/cve_bin_tool/format_checkers.py), if you're curious.
+
+You can view all the config files for GitHub Actions (what we use for Continous Integration (CI)) in [the .github/workflows directory](https://github.com/intel/cve-bin-tool/tree/main/.github/workflows).
+
 ## Making a new branch & pull request
 
 Git allows you to have "branches" with variant versions of the code.  You can see what's available using `git branch` and switch to one using `git checkout branch_name`.
@@ -225,8 +234,14 @@ When you're ready to share that branch to make a pull request, make sure you've
 
 Use `git add FILENAME` to add the files you want to put in your pull request, and use `git commit` to check them in.  Try to use [a clear commit message](https://chris.beams.io/posts/git-commit/) and use the [Conventional Commits](https://www.conventionalcommits.org/) format.  
 
+### Commit message tips
+
 We usually merge pull requests into a single commit when we accept them, so it's fine if you have lots of commits in your branch while you figure stuff out, and we can fix your commit message as needed then.  But if you make sure that at least the title of your pull request follows the [Conventional Commits](https://www.conventionalcommits.org/) format that you'd like for that merged commit message, that makes our job easier!
 
+GitHub also has some keywords that help us link issues and then close them automatically when code is merged.  The most common one you'll see us use looks like `fixes: #123456`. You can put this in the title of your PR (what usually becomes the commit message when we merge your code), another line in the commit message, or any comment in the pull request to make it work.  You and read more about [linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) in the GitHub documentation.
+
+### Sharing your code with us
+
 Once your branch is ready and you've checked in all your code, push it to your fork:
 
 ```bash
@@ -251,8 +266,9 @@ Here's a quick checklist to help you make sure your pull request is ready to go:
 4. Have I added or updated any documentation if I changed or added a feature?
    - New features are often documented in [MANUAL.md](https://github.com/intel/cve-bin-tool/blob/main/doc/MANUAL.md).  (See [Making documentation](#making-documentation) for more information.)
 5. Have I used [Conventional Commits](https://www.conventionalcommits.org/) to format the title of my pull request?
-6. Have I checked on the results from GitHub Actions?
-   - GitHub Actions will run all the tests, linters and a spell check for you.  if you can, try to make sure everything is running cleanly with no errors before leaving it for a human code reviewer!  
+6. If I closed a bug, have I linked it using one of [Github's keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)? (e.g. include the text `fixed #1234`)
+7. Have I checked on the results from GitHub Actions?
+   - GitHub Actions will run all the tests, linters and a spell check for you.  If you can, try to make sure everything is running cleanly with no errors before leaving it for a human code reviewer!
    - As of this writing, tests take less than 20 minutes to run once they start, but they can be queued for a while before they start.  Go get a cup of tea or work on something else while you wait!
 
 ## Code Review
@@ -275,7 +291,7 @@ Most of our "style" stuff is caught by the `black` and `flake8` linters, but we
 
 Python provides many different ways to format the string(you can read about them [here](https://realpython.com/python-formatted-output/))and we use f-string formatting in our tool.
 
-**Note: As f-strings are only supported in python 3.6+.** Please make sure you have version >=3.6
+> Note: f-strings are only supported in python 3.6+.
 
 - **Example:** Formatting string using f-string
 

README.md

@@ -214,6 +214,8 @@ This tool is meant to be used as a quick-to-run, easily-automatable check in a
 non-malicious environment so that developers can be made aware of old libraries
 with security issues that have been compiled into their binaries.
 
+If you are using the binary scanner capabilities, be aware that we only have a limited number of binary checkers (see table above) so we can only detect those libraries. Contributions of new checkers are always welcome! You can also use an alternate way to detect components (for example, a bill of materials tool such as [tern](https://github.com/tern-tools/tern)) and then use the resulting list as input to cve-bin-tool to get a more comprehensive vulnerability list.
+
 ## Requirements
 
 To use the auto-extractor, you may need the following utilities depending on the
@@ -239,7 +241,7 @@ On windows systems, you may need:
 - `Expand`
 - `pdftotext`
 
-Windows has `ar` and `Expand` installed in default, but `7z` in particular might need to be installed.
+Windows has `ar` and `Expand` installed by default, but `7z` in particular might need to be installed.
 If you want to run our test-suite or scan a zstd compressed file, We recommend installing this [7-zip-zstd](https://github.com/mcmilk/7-Zip-zstd)
 fork of 7zip. We are currently using `7z` for extracting `jar`, `apk`, `msi`, `exe` and `rpm` files.