Merge pull request #5 from openconfig/update-readme

Update README with section on updating existing repos to the latest workflow.

README.md

@@ -1,6 +1,21 @@
 # Common CI workflows for OpenConfig Projects
 
-## Standard Usage
+## Upgrading CI Version
+
+When updating a repository to use the latest reusable CI workflow on the main
+branch, `<latest SHA>` should be used following the safest security and
+stability recommendations:
+[Stability Recommendations](https://docs.github.com/en/actions/using-workflows/reusing-workflows#calling-a-reusable-workflow)
+
+Do this by simply updating the SHA in the user repository's
+`.github/workflows/go.yml` to the SHA of the current main branch
+([example](https://github.com/openconfig/kne/pull/371/files#diff-678682767f2477de3e3c546746f8568b9a1942b2c647d32331d7e774b8ff8d9f)).
+If you created a PR to update the reusable workflow, then this will be available
+after the PR is merged.
+
+## First-time Use
+
+### Standard Go Usage
 
 Copy the following into your repository's `.github/workflows/go.yml`:
 
@@ -16,10 +31,10 @@ on:
 
 jobs:
   go:
-    uses: openconfig/common-ci/.github/workflows/go.yml@v1.0.0
+    uses: openconfig/common-ci/.github/workflows/go.yml@<latest SHA>
 
   linter:
-    uses: openconfig/common-ci/.github/workflows/linter.yml@v1.0.0
+    uses: openconfig/common-ci/.github/workflows/linter.yml@<latest SHA>
 ```
 
 Then copy the sample linter configurations folder into your repository:
@@ -31,7 +46,7 @@ cp -r common-ci/.github/linters YOUR-REPO/.github/linters
 At this point, you may wish to change the configuration of these linters to suit
 your own repository.
 
-## Basic Usage
+### Basic Go Usage (for simple Go repositories)
 
 If you do not want to maintain linter configuration, then you may use the basic
 workflow, which only involves copying the following into your repository's
@@ -49,17 +64,17 @@ on:
 
 jobs:
   go:
-    uses: openconfig/common-ci/.github/workflows/basic_go.yml@v1.0.0
+    uses: openconfig/common-ci/.github/workflows/basic_go.yml@<latest SHA>
 ```
 
-## Flags
+### Flags
 
 Some flags are supported for customizing the CI workflow, for example,
 
 ```yaml
 jobs:
   go:
-    uses: openconfig/common-ci/.github/workflows/basic_go.yml@v1.0.0
+    uses: openconfig/common-ci/.github/workflows/basic_go.yml@<latest SHA>
     with:
       static-analysis-excludes-regex: exampleoc
       skip-gofmt: true