Add documentation on how to upgrade

1 files changed, 38 insertions, 2 deletions

diff --git a/README.md b/README.md
index 904d490..b976fb7 100644
--- a/README.md
+++ b/README.md
@@ -38,12 +38,18 @@ You can then run License Management on some target directory:
 docker run --rm --volume "/path/to/my/project":/code license-management analyze /code
 ```
 
-You can run integration tests on the image like this:
+You can run the QA tests using the following command:
 
 ```sh
 ./bin/test-all
 ```
 
+Or you can run a specific QA test using the following command:
+
+```sh
+QA_PROJECT=project_name QA_REF=git_ref ./bin/test
+```
+
 where:
 
 - `project_name` is the project slug among the
@@ -105,7 +111,6 @@ or its shorthand form (`--env MY_SETTING_VAR`) if the configuration comes from a
 *Tip:* in case you still need to run tests during license management check, supply `MAVEN_CLI_OPTS=-DskipTests=false`
 to the docker command.
 
-
 ## Versioning and release process
 
 1. Create a new entry in the `.gitlab/release.yml` file for the new version to release.
@@ -126,6 +131,37 @@ to the docker command.
 
 Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md).
 
+## Upgrading to the latest version of LicenseFinder
+
+The License Management projects depends on two different upstream components.
+
+1. The [LicenseFinder](https://rubygems.org/gems/license_finder) Ruby gem.
+2. The [LicenseFinder](https://hub.docker.com/r/licensefinder/license_finder) Docker image.
+
+Upgrading each can be performed as two separate changes and do not need to occur simultaneously,
+unless a new package manager has been added and additional tooling needs to be installed.
+
+### Upgrading the Ruby gem
+
+1. Check for the latest version of `LicenseFinder` at [https://rubygems.org/gems/license_finder](https://rubygems.org/gems/license_finder)
+1. Check the version of the `license_finder` gem that is currently being used in the `Gemfile.lock`. E.g. [here](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/39afdc40296871d9f7c1732ff3f7e1e3b7b28bbe/Gemfile.lock#L15)
+1. If an update is available, create a new branch
+1. Bump the license management version in [CHANGELOG.md](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/CHANGELOG.md) and in [version.rb](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/lib/license/management/version.rb)
+1. Update the `license_finder` version constraint in the [gemspec](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/39afdc40296871d9f7c1732ff3f7e1e3b7b28bbe/license-management.gemspec#L30).
+1. Run `bundle update license_finder`
+1. Test the changes locally using the `bin/test-all` script.
+1. Submit a merge request.
+
+### Upgrading the Docker image
+
+1. Check for the latest version of `LicenseFinder` at [https://hub.docker.com/r/licensefinder/license_finder/tags](https://hub.docker.com/r/licensefinder/license_finder/tags)
+1. Check the version of `license_finder` docker image that is currently being used in the `Dockerfile`. E.g. [here](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/39afdc40296871d9f7c1732ff3f7e1e3b7b28bbe/Dockerfile#L1)
+1. If an update is available, create a branch
+1. Bump the license management version in [CHANGELOG.md](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/CHANGELOG.md) and in [version.rb](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/lib/license/management/version.rb)
+1. Edit the version specified in the `DockerFile` to match the desired `license_finder` Docker image tag.
+1. Test the changes locally using the `bin/test-all` script.
+1. Submit a merge request.
+
 # Contributing
 
 If you want to help, read the [contribution guidelines](CONTRIBUTING.md).