ci: add documentation + refactor

CONTRIBUTING.md

@@ -1,8 +1,8 @@
-## Contributing
+# Contributing
 
 Open the project in Xcode and build by Product -> Build.
 
-### Linting code
+## Linting code
 
 Code is automatically linted during a build in Xcode. If you need to manually lint:
 
@@ -11,15 +11,25 @@ brew install swiftlint
 swiftlint
 ```
 
-### Formatting code
+## Formatting code
 
 You can automatically format your code using:
 
 ```shell
 ./scripts/swift-format
 ```
 
-### Running tests
+## API diffs
+We run a script to make sure that we don't make changes to the public API without intending to.
+The diff script and the script to generate a new "golden api file" uses a tool called [SourceKitten](https://github.com/jpsim/SourceKitten) which can be installed using homebrew (`brew install sourcekitten`).
+
+### The expected workflow is:
+* Write code (that may change the public API).
+* Optionally run ./scripts/api_diff.sh to detect the api change.
+* Run ./scripts/generate_public_api.sh -- this will update the file in ./api.
+* Commit both code and updated API in the same commit. 
+
+## Running tests
 
 IT tests require a Confidence client token to reach remote servers. The token can be created on the Confidence portal. 
 The Confidence organization used for IT tests is named `confidence-test` (you may need to request access).

scripts/api_diff.sh

@@ -17,7 +17,7 @@ rm $script_dir/raw_api.json
 # Compare the public API with the previous public API and exit with 1 if there are changes
 echo "Comparing genereated public API with previous public API"
 set +e
-git diff --no-index --exit-code $script_dir/public_api.json $script_dir/current_public_api.json
+git diff --no-index --exit-code $root_dir/api/public_api.json $script_dir/current_public_api.json
 # Capture the exit code of the git diff command
 diff_exit_code=$?
 set -e

scripts/generate_public_api_list.sh → scripts/generate_public_api.sh

@@ -9,7 +9,7 @@ root_dir="$script_dir/../"
 sourcekitten doc --module-name Confidence -- -scheme Confidence-Package -destination 'platform=iOS Simulator,name=iPhone 15,OS=17.2' > $script_dir/raw_api.json
 
 # Extract the public API from the raw api json file
-python3 $script_dir/extract_public_funcs.py $script_dir/raw_api.json $script_dir/public_api.json
+python3 $script_dir/extract_public_funcs.py $script_dir/raw_api.json $root_dir/api/public_api.json
 
 # Clean up the raw api json file
 rm $script_dir/raw_api.json