Update stable branch to main (#243)

* Fix nothing to migrate bug (#231) * handle case where default branch and discourse are in-line but base is not for the migration case * Add a formatted representation of the UpdatePageAction dataclass (#230) * Add a formatted representation of the UpdatePageAction dataclass * Update changelog * Add return value to docstring * Include return type * Apply lint changes * Include a string representation of the class, which many tests check for * fix linting (#234) * Update python Docker tag to v3.12 (#220) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: arturo-seijas <[email protected]> * Update dependency more-itertools to >=10.2,<10.3 (#229) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: arturo-seijas <[email protected]> * Update dependency PyGithub to >=2.2,<2.3 (#233) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: arturo-seijas <[email protected]> Co-authored-by: Christopher Bartz <[email protected]> * Update dependency pytest to v8 (#232) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: arturo-seijas <[email protected]> * Create bot_pr_approval.yaml (#236) * Removed `discourse-gatekeeper/discourse-ahead-ok` (#235) * feat(ISD-1567): removed obsolete code and corresponding documentation * feat(ISD-1498): removed check in test_check for the removed tag * feat(ISD-1498): updated test parameters to account for removal of discourse ahead tag removal * feat(ISD-1498): removed tagged argument from tests * feat(ISD-1498): ensured all parameters return only 2 values in tuple * feat(ISD-1498): removed ahead tag from constants file, removed mention in integration tests * feat(ISD-1498): removed ahead tag from check.py * feat(ISD-1498): rectified erroneous deletion of expected problem in test check * feat(ISD-1498): adhered to linting requirements by removing unused src.constants imports * feat(ISD-1498): fixed all linting issues and fixed method signatures. * feat(ISD-1498): removed test case 7 from test conflicts * feat(ISD-1498): removed test 7 * feat(ISD-1498): fixed linting issues * feat(ISD-1498): updated change log with new version details * feat(ISD-1498): added src-docs * feat(ISD-1498): fixed comments in run_conflict integration test * feat(ISD-1498): removed assert associated with removed act * Prepare discourse-gatekeeper for PAAS app charmer (#238) New input parameter `charm-dir`, that defines where to look for `metadata.yaml`, `charmcraft.yaml` or the docs directory. If `metadata.yaml` does not exist, `charmcraft.yaml` is used instead. * conflict change race condition resolution stage 1 (#241) * add check that content has not changed on discourse before updating the content * New version v0.9.0 (#242) --------- Co-authored-by: David Andersson <[email protected]> Co-authored-by: mthaddon <[email protected]> Co-authored-by: arturo-seijas <[email protected]> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: Christopher Bartz <[email protected]> Co-authored-by: Brendan Bell <[email protected]>
canonical · Apr 4, 2024 · b655fad · b655fad
1 parent 6556d9a
commit b655fad
Show file tree

Hide file tree

Showing 77 changed files with 849 additions and 389 deletions.
diff --git a/.github/workflows/bot_pr_approval.yaml b/.github/workflows/bot_pr_approval.yaml
@@ -0,0 +1,10 @@
+name: Provide approval for bot PRs
+
+on:
+  pull_request:
+
+jobs:
+  bot_pr_approval:
+    uses: canonical/operator-workflows/.github/workflows/bot_pr_approval.yaml@main
+    secrets: inherit
+
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,37 @@
 # Changelog
 
-## [Unreleased]
+## Unreleased
+
+## [v0.9.0] - 2024-04-04
+
+### Added
+
+- Added a formatted representation of the UpdatePageAction dataclass for more
+  human-readable output.
+- To address a race condition between the conflict check and when content is
+  updated on discourse, the action now checks that the content hasn't changed
+  since the conflict check was completed, before pushing updates to discourse.
+- If metadata.yaml does not exist, read the name and doc information from the
+  charmcraft.yaml file.
+- New input environment variable INPUT_CHARM_DIR. metadata.yaml or charmcraft.yaml
+  will be read from this directory instead of the base one and the documentation
+  will also be searched under this directory.
+
+## [v0.8.2] - 2024-02-16
+
+### Fixed
+
+- Removed soft-conflict ignore button. `discourse-ahead-ok` tag, which was used
+  to indicate changes between discourse and git should no longer be used. Has been
+  removed, with tests updated to reflect this.
+
+## [v0.8.1] - 2024-01-18
+
+### Fixed
+
+- Migration error where discourse is in-line with the default branch but the
+  base content tag is behind. This no longer attempts migration and now also
+  moves the tag to the latest commit on the default branch.
 
 ## [v0.8.0] - 2023-11-30
 

diff --git a/Dockerfile b/Dockerfile
@@ -1,6 +1,6 @@
-# Copyright 2023 Canonical Ltd.
+# Copyright 2024 Canonical Ltd.
 # See LICENSE file for licensing details.
-FROM python:3.11-slim
+FROM python:3.12-slim
 
 RUN apt-get update && \
     apt-get install -y --no-install-recommends git=1:2.39.* && \

diff --git a/README.md b/README.md
@@ -210,11 +210,6 @@ that have not been merged into `main` and a PR proposes changes to
 `docs/architecture.md` could make changes to the documentation that mean that
 the changes to `docs/getting-started.md` are no longer accurate.
 
-If, after checking the community contributions on discourse, you determine that
-there are no logical conflicts, the `discourse-gatekeeper/discourse-ahead-ok` tag
-can be applied to the latest commit in the PR which will allow the action to
-proceed assuming there are no page-by-page conflicts.
-
 ## Contents Index
 
 The `docs/index.md` file may contain a `# contents` section which is used to

diff --git a/action.yaml b/action.yaml
@@ -1,4 +1,4 @@
-# Copyright 2023 Canonical Ltd.
+# Copyright 2024 Canonical Ltd.
 # See LICENSE file for licensing details.
 name: Upload Charm Docs
 description: Upload charm documentation to charmhub
@@ -55,6 +55,14 @@ inputs:
       variable GITHUB_SHA.
     required: false
     type: string
+  charm_dir:
+    description: |
+      Relative name of the directory where the metadata.yaml or charmcraft.yaml files are located
+      if they are not in the root directory of the repository. The docs directory is also located
+      under this directory.
+    default: ''
+    required: false
+    type: string
 outputs:
   index_url:
     description: |

diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -2,5 +2,5 @@ ops
 pytest-operator
 factory_boy>=3,<4
 pytest-asyncio>=0.21,<0.22
-pytest>=7,<8
+pytest>=8,<9
 juju==3.1.2.0
diff --git a/generate-src-docs.sh b/generate-src-docs.sh
@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-# Copyright 2023 Canonical Ltd.
+# Copyright 2024 Canonical Ltd.
 # See LICENSE file for licensing details.
 
 rm -rf src-docs

diff --git a/main.py b/main.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-# Copyright 2023 Canonical Ltd.
+# Copyright 2024 Canonical Ltd.
 # See LICENSE file for licensing details.
 
 """Main execution for the action."""
@@ -45,6 +45,7 @@ def _parse_env_vars() -> types_.UserInputs:
     github_access_token = os.getenv("INPUT_GITHUB_TOKEN")
     base_branch = os.getenv("INPUT_BASE_BRANCH", DEFAULT_BRANCH)
     commit_sha = os.getenv("INPUT_COMMIT_SHA")
+    charm_dir = os.getenv("INPUT_CHARM_DIR", "")
 
     event_path = os.getenv("GITHUB_EVENT_PATH")
     if not event_path:
@@ -79,6 +80,7 @@ def _parse_env_vars() -> types_.UserInputs:
         github_access_token=github_access_token,
         commit_sha=commit_sha,
         base_branch=base_branch,
+        charm_dir=charm_dir,
     )
 
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,4 +1,4 @@
-# Copyright 2023 Canonical Ltd.
+# Copyright 2024 Canonical Ltd.
 # See LICENSE file for licensing details.
 
 [tool.bandit]

diff --git a/requirements.txt b/requirements.txt
@@ -1,6 +1,6 @@
 GitPython>=3.1,<3.2
 pydiscourse>=1.6,<1.7
-PyGithub>=2.1,<2.2
+PyGithub>=2.2,<2.3
 PyYAML>=6.0,<6.1
 requests>=2.31,<2.32
-more-itertools>=10.1,<10.2
+more-itertools>=10.2,<10.3
diff --git a/src-docs/__init__.py.md b/src-docs/__init__.py.md
@@ -9,7 +9,6 @@ Library for uploading docs to charmhub.
 ---------------
 - **DRY_RUN_NAVLINK_LINK**
 - **FAIL_NAVLINK_LINK**
-- **DOCUMENTATION_FOLDER_NAME**
 - **DOCUMENTATION_TAG**
 - **DEFAULT_BRANCH_NAME**
 - **GETTING_STARTED**
@@ -51,7 +50,7 @@ Upload the documentation to charmhub.
 
 ---
 
-<a href="../src/__init__.py#L195"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/__init__.py#L191"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `run_migrate`
 
@@ -76,7 +75,7 @@ Migrate existing docs from charmhub to local repository.
 
 ---
 
-<a href="../src/__init__.py#L251"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/__init__.py#L255"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `pre_flight_checks`
 

diff --git a/src-docs/action.py.md b/src-docs/action.py.md
@@ -15,7 +15,7 @@ Module for taking the required actions to match the server state with the local
 
 ---
 
-<a href="../src/action.py#L431"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/action.py#L444"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `run_all`
 

diff --git a/src-docs/check.py.md b/src-docs/check.py.md
@@ -11,7 +11,7 @@ Module for running checks.
 
 ---
 
-<a href="../src/check.py#L55"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/check.py#L53"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `get_path_with_diffs`
 
@@ -37,15 +37,13 @@ Generate the paths that have either local or server content changes.
 
 ---
 
-<a href="../src/check.py#L161"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/check.py#L159"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `conflicts`
 
 ```python
 conflicts(
-    actions: Iterable[CreateGroupAction | CreatePageAction | CreateExternalRefAction | NoopGroupAction | NoopPageAction | NoopExternalRefAction | UpdateGroupAction | UpdatePageAction | UpdateExternalRefAction | DeleteGroupAction | DeletePageAction | DeleteExternalRefAction],
-    repository: Client,
-    user_inputs: UserInputs
+    actions: Iterable[CreateGroupAction | CreatePageAction | CreateExternalRefAction | NoopGroupAction | NoopPageAction | NoopExternalRefAction | UpdateGroupAction | UpdatePageAction | UpdateExternalRefAction | DeleteGroupAction | DeletePageAction | DeleteExternalRefAction]
 ) → Iterator[Problem]
 ```
 
@@ -60,8 +58,6 @@ The second type of conflict is a logical conflict which arises out of that there
 **Args:**
 
  - <b>`actions`</b>:  The actions to check. 
- - <b>`repository`</b>:  Client for repository interactions. 
- - <b>`user_inputs`</b>:  Configuration from the user. 
 
 
 
@@ -71,7 +67,7 @@ The second type of conflict is a logical conflict which arises out of that there
 
 ---
 
-<a href="../src/check.py#L273"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/check.py#L259"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `external_refs`
 

diff --git a/src-docs/constants.py.md b/src-docs/constants.py.md
@@ -11,7 +11,6 @@ The use of this module should be limited to cases where the constant is not bett
 ---------------
 - **DEFAULT_BRANCH**
 - **DOCUMENTATION_TAG**
-- **DISCOURSE_AHEAD_TAG**
 - **DOCUMENTATION_FOLDER_NAME**
 - **DOC_FILE_EXTENSION**
 - **DOCUMENTATION_INDEX_FILENAME**

diff --git a/src-docs/docs_directory.py.md b/src-docs/docs_directory.py.md
@@ -8,7 +8,6 @@ Class for reading the docs directory.
 **Global Variables**
 ---------------
 - **DOC_FILE_EXTENSION**
-- **DOCUMENTATION_FOLDER_NAME**
 
 ---
 
@@ -67,7 +66,7 @@ Algorithm:  1.  Get a list of all sub directories and .md files in the docs fold
 ## <kbd>function</kbd> `has_docs_directory`
 
 ```python
-has_docs_directory(base_path: Path) → bool
+has_docs_directory(docs_path: Path) → bool
 ```
 
 Return existence of docs directory from base path. 
@@ -76,7 +75,7 @@ Return existence of docs directory from base path.
 
 **Args:**
 
- - <b>`base_path`</b>:  Base path of the repository to search the docs directory from 
+ - <b>`docs_path`</b>:  Docs path of the repository where docs are 
 
 
 

diff --git a/src-docs/download.py.md b/src-docs/download.py.md
@@ -5,13 +5,10 @@
 # <kbd>module</kbd> `download.py`
 Library for downloading docs folder from charmhub. 
 
-**Global Variables**
----------------
-- **DOCUMENTATION_FOLDER_NAME**
 
 ---
 
-<a href="../src/download.py#L39"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/download.py#L38"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `recreate_docs`
 

diff --git a/src-docs/index.py.md b/src-docs/index.py.md
@@ -8,20 +8,19 @@ Execute the uploading of documentation.
 **Global Variables**
 ---------------
 - **DOC_FILE_EXTENSION**
-- **DOCUMENTATION_FOLDER_NAME**
 - **DOCUMENTATION_INDEX_FILENAME**
 - **NAVIGATION_HEADING**
 - **CONTENTS_HEADER**
 - **CONTENTS_END_LINE_PREFIX**
 
 ---
 
-<a href="../src/index.py#L55"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/index.py#L50"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `get`
 
 ```python
-get(metadata: Metadata, base_path: Path, server_client: Discourse) → Index
+get(metadata: Metadata, docs_path: Path, server_client: Discourse) → Index
 ```
 
 Retrieve the local and server index information. 
@@ -31,7 +30,7 @@ Retrieve the local and server index information.
 **Args:**
 
  - <b>`metadata`</b>:  Information about the charm. 
- - <b>`base_path`</b>:  The base path to look for the metadata file in. 
+ - <b>`docs_path`</b>:  The base path to look for the documentation. 
  - <b>`server_client`</b>:  A client to the documentation server. 
 
 
@@ -48,7 +47,7 @@ Retrieve the local and server index information.
 
 ---
 
-<a href="../src/index.py#L90"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/index.py#L85"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `contents_from_page`
 
@@ -72,7 +71,7 @@ Get index file contents from server page.
 
 ---
 
-<a href="../src/index.py#L205"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/index.py#L200"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `get_content_for_server`
 
@@ -96,7 +95,7 @@ Get the contents from the index file that should be passed to the server.
 
 ---
 
-<a href="../src/index.py#L262"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/index.py#L257"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `classify_item_reference`
 
@@ -124,7 +123,7 @@ Classify the type of a reference.
 
 ---
 
-<a href="../src/index.py#L414"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/index.py#L409"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `get_contents`
 

diff --git a/src-docs/metadata.py.md b/src-docs/metadata.py.md
@@ -7,13 +7,17 @@ Module for parsing metadata.yaml file.
 
 **Global Variables**
 ---------------
+- **CHARMCRAFT_FILENAME**
+- **CHARMCRAFT_NAME_KEY**
+- **CHARMCRAFT_LINKS_KEY**
+- **CHARMCRAFT_LINKS_DOCS_KEY**
 - **METADATA_DOCS_KEY**
 - **METADATA_FILENAME**
 - **METADATA_NAME_KEY**
 
 ---
 
-<a href="../src/metadata.py#L18"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/metadata.py#L22"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `get`
 
@@ -23,11 +27,13 @@ get(path: Path) → Metadata
 
 Check for and read the metadata. 
 
+The charm metadata can be in the file metadata.yaml or in charmcraft.yaml. From charmcraft version 2.5, the information should be in charmcraft.yaml, and the user should only modify that file. This function does not consider the case in which the name is in one file and the doc link is in the other. 
+
 
 
 **Args:**
 
- - <b>`path`</b>:  The base path to look for the metadata file in. 
+ - <b>`path`</b>:  The base path to look for the metadata files. 
 
 
 
@@ -38,6 +44,6 @@ Check for and read the metadata.
 
 **Raises:**
 
- - <b>`InputError`</b>:  if the metadata file does not exists or is malformed. 
+ - <b>`InputError`</b>:  if the metadata file does not exist or is malformed.
-Original file line number
+Diff line change
@@ Expand Up @@
     ---
-    <a href="../src/action.py#L431"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+    <a href="../src/action.py#L444"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
     ## <kbd>function</kbd> `run_all`
@@ Expand Down @@