PR tweaks

CONTRIBUTING.md

@@ -1,11 +1,9 @@
 ## Filing Bugs
-
-File bugs at https://github.com/canonical/jimm/issues
+File bugs at https://github.com/canonical/jimm/issues.
 
 ## Testing
-
-Many tests in JIMM require real services to be reachable i.e. Postgres, Vault and 
-OpenFGA and an IdP (Identity Provider).
+Many tests in JIMM require real services to be reachable i.e. Postgres, Vault, OpenFGA 
+and an IdP (Identity Provider).
 
 JIMM's docker compose file provides a convenient way of starting these services.
 
@@ -15,6 +13,7 @@ Run:
 $ make test-env
 $ go test ./...
 ```
+
 ### Pre-requisite
 To check if your system has all the prequisites installed simply run `make sys-deps`.
 This will check for all test prequisites and inform you how to install them if not installed. 
@@ -29,20 +28,20 @@ Tests inside of `cmd/` and `internal/jujuapi/` are integration based, spinning u
 a Juju controller for testing. To spin up a Juju controller we use the `JujuConnSuite` which 
 in turn uses the [gocheck](http://labix.org/gocheck) test library.
 
-Because of the `JujuConnSuite`, there 2 test libraries in JIMM,
+Because of the `JujuConnSuite` and its use in JIMM's test suites, there are 2 test libraries in JIMM:
 - GoCheck based tests, identified in the function signature with `func Test(c *gc.C)`.
   - These tests normally interact with a Juju controller.
   - GoCheck should only be used when using the suites in `internal/jimmtest`.
-- Regular Go `testing.T` tests, identified in the function signature with `func Test(t *testing.T)`.
+- Stdlib `testing.T` tests, identified in the function signature with `func Test(t *testing.T)`.
   - These tests vary in their scope but do not require a Juju controller.
   - To provide assertions, the project uses [quicktest](https://github.com/frankban/quicktest), 
     a lean testing library.
 
-Because many tests rely on PostgreSQL, OpenFGA and Hashicorp Vault which are dockerised 
-you may simple run `make test-env` to be integration test ready.
+Because many tests rely on PostgreSQL, OpenFGA and Vault which are dockerised 
+you may simply run `make test-env` to be integration test ready.
 
 The above command won't start a dockerised instance of JIMM as tests are normally run locally. 
-Instead, to start a  dockerised JIMM that will auto-reload on code changes, follow the instructions 
+Instead, to start a dockerised JIMM that will auto-reload on code changes, follow the instructions 
 in `local/README.md`.
 
 ### Manual commands

README.md

@@ -20,9 +20,9 @@ acting together to enable storing state, storing secrets and auth.
 ## Features
 
 JIMM/JAAS provides enterprise level functionality layered on top of your Juju controller like:
-- Federated user management to an external identity provider using OAuth 2.0 and OIDC.
+- Federated login via an external identity provider using OAuth2.0 and OIDC.
 - Fine grained access control with the ability to create user groups.
-- Simplified networking, exposing a single gateway into your Juju estate.
+- A single gateway into your Juju estate.
 - The ability to query for information across all your Juju controllers.
 
 For a full overview of the capabilties, check out 
@@ -35,16 +35,18 @@ The project uses [Go modules](https://golang.org/cmd/go/#hdr-Module_maintenance)
 Go dependencies. **Note: Go 1.11 or greater needed.**
 
 A brief explanation of the various services that JIMM depends on is below:
-- Vault: User's cloud-credentials are stored in Vault. Cloud-credentials are API keys that 
+- Vault: User cloud-credentials and private keys are stored in Vault. Cloud-credentials are API keys that 
 enable Juju to communicate with a cloud's API.
-- Postgres: A majority of JIMM's state is stored in Postgres.
-- OpenFGA: A cloud-native authorisation tool where authorisation rules are stored and queried 
+- Postgres: All non-sensitive state is stored in Postgres.
+- OpenFGA: A distributed authorisation server where authorisation rules are stored and queried 
 using relation based access control.
-- IdP: An identity provider, utilising OAuth 2.0 and OIDC, JIMM delegates authentication to a 
-separate identity service.
+- IdP: An identity provider which supports OAuth2.0 and OIDC.
 
 ## JIMM versioning
 
+tldr; JIMM v3 is intended to support Juju v3 controllers AND the last minor version 
+of the previous major (Juju v2.9) for migration purposes.
+
 JIMM v0 and v1 follow a different versioning strategy than future releases. JIMM v0 was the initial
 release and used MongoDB to store state. JIMM v1 was an upgrade that switched to using PostgreSQL 
 for storing state but still retained similar functionality to v0.  
@@ -53,7 +55,7 @@ These versions worked with Juju v2 and v3.
 Subsequently JIMM introduced a large shift in how the service worked:
 - JIMM now acts as a proxy between all client and Juju controller interactions. Previously 
 users were redirected to a Juju controller.
-- Juju controllers trust a public key served by JIMM.
+- Juju controllers support JWT login where secure tokens are issued by JIMM.
 - JIMM acts as an authorisation gateway creating trusted short-lived JWT tokens to authorize 
 user actions against Juju controllers.
 
@@ -65,13 +67,9 @@ Further, to better align the two projects, JIMM's versioning now aligns with Juj
 As a result of this, there is no JIMM v2 and instead from JIMM v3, the versioning strategy 
 we follow is to match JIMM's major version to the corresponding Juju major version we support.
 
-As an example, JIMM v3 is intended to support Juju v3 controllers AND the last minor version 
-of the previous major (Juju v2.9) for migration purposes.
-
-
 ## Binaries
 
-This repo contains 3 binaries:
+This repository contains 3 binaries:
 - jimmsrv: The JIMM server.
 - jimmctl: A CLI tool for administrators of JIMM to view audit logs, manage permissions, etc. 
 Available as a snap.