From 08b69e370579c6ebe38bbf38b20fd4fa069c7bf2 Mon Sep 17 00:00:00 2001
From: Pradeep Tammali <pradeepkumartammali@gmail.com>
Date: Sun, 23 Jun 2024 12:57:36 +0200
Subject: [PATCH] chore: make it ready for v2

---
 Makefile            |  7 +++++--
 README.md           |  2 +-
 docs/annotations.md | 31 +++++++++++++++++++++++++++++++
 3 files changed, 37 insertions(+), 3 deletions(-)
 create mode 100644 docs/annotations.md

diff --git a/Makefile b/Makefile
index fce5dbb..6746b26 100644
--- a/Makefile
+++ b/Makefile
@@ -26,10 +26,13 @@ report:
 	pipenv run pytest tests  --cov-branch --cov=codecov --cov-report=term-missing --cov-report=json:/tmp/report.json
 
 build:
-	python3 -m build
+	pipenv run python3 -m build
+
+test-publish:
+	pipenv run python3 -m twine upload --repository testpypi dist/*
 
 publish:
-	python3 -m twine upload dist/*
+	pipenv run python3 -m twine upload dist/*
 
 run:
 	pipenv run python run.py
diff --git a/README.md b/README.md
index eefe48d..1571590 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ Permissions needed for the Github Token:
 `Pull requests:write`
 
 If you have given `ANNOTATIONS_DATA_BRANCH` branch then Github Token also requires content write permissions.
-Read more on how to use this here.
+Read more on how to use this [here](./docs/annotations.md).
 
 `Contents:write`
 
diff --git a/docs/annotations.md b/docs/annotations.md
new file mode 100644
index 0000000..1312448
--- /dev/null
+++ b/docs/annotations.md
@@ -0,0 +1,31 @@
+# How Annotations Work
+
+Annotations in this context are similar to GitHub annotations or workflow commands,
+displaying a banner in the GitHub pull request.
+When the option `ANNOTATE_MISSING_LINES=True` is enabled, annotations are generated for lines missing coverage.
+To include branch coverage in these annotations, enable `BRANCH_COVERAGE=True`.
+By default, these annotations are written to the console, but you can also choose to save them elsewhere.
+
+## Storing Annotations
+
+1. **To a File**:
+   - Set the file path in `ANNOTATIONS_OUTPUT_PATH`.
+
+2. **To a Branch**:
+   - Set the branch name in `ANNOTATIONS_DATA_BRANCH`.
+   - Ensure your GitHub token has `Contents:write` permissions.
+   - Make sure the branch exists and is not protected by branch protection rules.
+   - Annotations are stored with the filename `{PR-number}-annotations.json`,
+   where `{PR-number}` is replaced by the actual PR number.
+   - Existing annotations for a PR in the branch will be overwritten if the file already exist in branch.
+   - If the GitHub token user has email privacy enabled, the email format `{id}+{login}@users.noreply.github.com` is used.
+   Where `{id}` is the user ID and `{login}` is the username.
+
+## Using the Annotations
+
+After generating the annotations, you can enable this extension.
+A URL is required where the annotations are accessible from the extension, with a placeholder for the PR number.
+For example:
+`https://raw.githubusercontent.com/PradeepTammali/python-coverage-comment/data/coverage-annotations/{PR-NUMBER}-annotations.json`
+
+The `{PR-NUMBER}` placeholder will be replaced with the actual PR number when viewing the PR diff.