From 064c6d4b58c89228548ecd5579855b57ad5a6627 Mon Sep 17 00:00:00 2001 From: Oliver Lipkau Date: Wed, 20 May 2026 00:03:01 +0200 Subject: [PATCH 1/4] Update JiraAgilePS submodule for canonical docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- modules/JiraAgilePS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/JiraAgilePS b/modules/JiraAgilePS index a2a8ea4..346ac95 160000 --- a/modules/JiraAgilePS +++ b/modules/JiraAgilePS @@ -1 +1 @@ -Subproject commit a2a8ea496a5f29b993c41bf24835572160560a7c +Subproject commit 346ac9506b26dc48bc24d28c6e0272a13af5e1e7 From c89b8a4eb9ebf5d4f6af21efe74c3186bf5a72d0 Mon Sep 17 00:00:00 2001 From: Oliver Lipkau Date: Sun, 24 May 2026 19:20:13 +0200 Subject: [PATCH 2/4] Align module documentation publishing --- .github/scripts/check-module-submodules.sh | 87 ++++++++++++++++++++++ .github/workflows/pages.yml | 3 + Gemfile | 1 + _data/index/modules.yml | 3 - _data/modules.yml | 27 +++++-- _data/navigation.yml | 4 +- docs/Contributing/index.md | 14 +++- docs/Contributing/module-documentation.md | 46 ++++++++++++ docs/Contributing/submitting-a-pr.md | 4 +- 9 files changed, 170 insertions(+), 19 deletions(-) create mode 100644 .github/scripts/check-module-submodules.sh create mode 100644 docs/Contributing/module-documentation.md diff --git a/.github/scripts/check-module-submodules.sh b/.github/scripts/check-module-submodules.sh new file mode 100644 index 0000000..f5da3ee --- /dev/null +++ b/.github/scripts/check-module-submodules.sh @@ -0,0 +1,87 @@ +#!/usr/bin/env bash +set -euo pipefail + +active_modules=( + "AtlassianPS.Configuration" + "ConfluencePS" + "JiraAgilePS" + "JiraPS" +) + +# Modules without tags can still have an explicit documentation baseline. +no_tag_baselines=( + "JiraAgilePS" +) + +# Keep docs-only exceptions narrow and remove them after the next module release. +docs_only_exceptions=( + "AtlassianPS.Configuration:555e8a3300a12e03b1d9c494a874fe21fe9bbccf" +) + +has_no_tag_baseline() { + local module="$1" + + for baseline in "${no_tag_baselines[@]}"; do + if [[ "$baseline" == "$module" ]]; then + return 0 + fi + done + + return 1 +} + +has_docs_only_exception() { + local module="$1" + local commit="$2" + + for exception in "${docs_only_exceptions[@]}"; do + if [[ "$exception" == "$module:$commit" ]]; then + return 0 + fi + done + + return 1 +} + +errors=0 + +for module in "${active_modules[@]}"; do + path="modules/$module" + + if [[ ! -d "$path/.git" && ! -f "$path/.git" ]]; then + printf '::error file=.gitmodules::%s submodule is not initialized at %s\n' "$module" "$path" + errors=$((errors + 1)) + continue + fi + + git -C "$path" fetch --tags --quiet origin + + if tag=$(git -C "$path" describe --tags --exact-match HEAD 2>/dev/null); then + printf '%s is release-aligned at %s.\n' "$module" "$tag" + continue + fi + + tag_count=$(git -C "$path" tag | wc -l | tr -d ' ') + commit=$(git -C "$path" rev-parse HEAD) + short_commit=$(git -C "$path" rev-parse --short HEAD) + + if [[ "$tag_count" == "0" ]] && has_no_tag_baseline "$module"; then + printf '::notice file=.gitmodules::%s has no tags; treating %s as the documented baseline.\n' "$module" "$short_commit" + continue + fi + + if has_docs_only_exception "$module" "$commit"; then + printf '::notice file=.gitmodules::%s points at docs-only exception %s. Move back to a release tag after the next module release.\n' "$module" "$short_commit" + continue + fi + + if [[ "$tag_count" == "0" ]]; then + printf '::error file=.gitmodules::%s is untagged and has no no-tags baseline exception.\n' "$module" + else + printf '::error file=.gitmodules::%s points at %s, which is not an exact release tag. Use a release tag or add a narrow docs-only exception in this script.\n' "$module" "$short_commit" + fi + + errors=$((errors + 1)) +done + +exit "$errors" diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index b75ce8f..04fe677 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -34,6 +34,9 @@ jobs: - name: Setup Pages uses: actions/configure-pages@v5 + - name: Check module submodules + run: bash .github/scripts/check-module-submodules.sh + - name: Build Jekyll run: bundle exec jekyll build --baseurl "" env: diff --git a/Gemfile b/Gemfile index 7a42359..592b0d7 100644 --- a/Gemfile +++ b/Gemfile @@ -2,3 +2,4 @@ source 'https://rubygems.org' gem 'github-pages', group: :jekyll_plugins gem "webrick", "~> 1.8" +gem "logger", "~> 1.6" diff --git a/_data/index/modules.yml b/_data/index/modules.yml index c7203ec..165e42f 100644 --- a/_data/index/modules.yml +++ b/_data/index/modules.yml @@ -1,7 +1,4 @@ -# projects section data -# - name: BitbucketPS - name: ConfluencePS -# - name: HipChatPS - name: JiraAgilePS - name: JiraPS - name: AtlassianPS.Configuration diff --git a/_data/modules.yml b/_data/modules.yml index 3668f48..d82d584 100644 --- a/_data/modules.yml +++ b/_data/modules.yml @@ -1,24 +1,35 @@ -# - name: BitbucketPS -# description: ToDo -# github: https://github.com/AtlassianPS/BitbucketPS -# path: /module/BitbucketPS - name: ConfluencePS description: A PowerShell module that interacts with Atlassian's Confluence wiki product. github: https://github.com/AtlassianPS/ConfluencePS path: /module/ConfluencePS -# - name: HipChatPS -# description: ToDo -# github: https://github.com/AtlassianPS/HipChatPS -# path: /module/HipChatPS + status: active - name: JiraAgilePS description: PowerShell module to interact with Jira's Agile plugin github: https://github.com/AtlassianPS/JiraAgilePS path: /module/JiraAgilePS + status: active - name: JiraPS description: PowerShell module to interact with Atlassian JIRA github: https://github.com/AtlassianPS/JiraPS path: /module/JiraPS + status: active - name: AtlassianPS.Configuration description: A module for AtlassianPS modules to use for managing connections github: https://github.com/AtlassianPS/AtlassianPS.Configuration path: /module/AtlassianPS.Configuration + status: active +- name: AtlassianPS + description: Legacy metapackage; not an active documentation target. + github: https://github.com/AtlassianPS/AtlassianPS + path: /module/AtlassianPS + status: legacy +- name: BitbucketPS + description: Legacy Bitbucket module; not an active documentation target. + github: https://github.com/AtlassianPS/BitbucketPS + path: /module/BitbucketPS + status: legacy +- name: HipChatPS + description: Legacy HipChat module; not an active documentation target. + github: https://github.com/AtlassianPS/HipChatPS + path: /module/HipChatPS + status: legacy diff --git a/_data/navigation.yml b/_data/navigation.yml index aee100b..d6fa249 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -38,7 +38,9 @@ - Classes - name: JiraAgilePS path: docs/JiraAgilePS - listChilds: true + groups: + - About + - Commands # - name: HipChatPS # path: docs/HipChatPS - name: JiraPS diff --git a/docs/Contributing/index.md b/docs/Contributing/index.md index 2e4eb0c..26b3493 100644 --- a/docs/Contributing/index.md +++ b/docs/Contributing/index.md @@ -32,15 +32,15 @@ Each of our projects has an _issue tracker_ where you can report your findings. | Project | Link | # of open issues | | ----------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **AtlassianPS** | | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/AtlassianPS.svg?maxAge=2592000)](https://github.com/AtlassianPS/AtlassianPS/issues) | | **AtlassianPS.Configuration** | | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/AtlassianPS.Configuration.svg?maxAge=2592000)](https://github.com/AtlassianPS/AtlassianPS.Configuration/issues) | | **AtlassianPS.github.io** | | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/AtlassianPS.github.io.svg?maxAge=2592000)](https://github.com/AtlassianPS/AtlassianPS.github.io/issues) | -| **BitbucketPS** | | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/BitbucketPS.svg?maxAge=2592000)](https://github.com/AtlassianPS/BitbucketPS/issues) | | **ConfluencePS** | | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/ConfluencePS.svg?maxAge=2592000)](https://github.com/AtlassianPS/ConfluencePS/issues) | -| **HipchatPS** | | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/HipchatPS.svg?maxAge=2592000)](https://github.com/AtlassianPS/HipchatPS/issues) | | **JiraAgilePS** | | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/JiraAgilePS.svg?maxAge=2592000)](https://github.com/AtlassianPS/JiraAgilePS/issues) | | **JiraPS** | | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/JiraPS.svg?maxAge=2592000)](https://github.com/AtlassianPS/JiraPS/issues) | +Legacy modules such as `AtlassianPS`, `BitbucketPS`, and `HipChatPS` are not active documentation targets on this website. +Use their GitHub repositories directly if you need historical source or issue context. + Before creating a new issue, please search open issues first. If a similar issue already exists, add your details there. @@ -74,7 +74,6 @@ clone the source code into a container volume, and spin up a dev container for u - [AtlassianPS](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/atlassianps/atlassianps) - [AtlassianPS.Configuration](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/atlassianps/atlassianps.configuration) - [AtlassianPS.github.io](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/atlassianps/atlassianps.github.io) -- [BitbucketPS](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/atlassianps/bitbucketps) - [ConfluencePS](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/atlassianps/confluenceps) - [JiraAgilePS](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/atlassianps/jiraagileps) - [JiraPS](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/atlassianps/jiraps) @@ -91,6 +90,13 @@ or by using the "Code" button in the repository itself, as shown below. Please follow [Our Guidelines](our-guidelines.html) when contributing code or docs. +## 📚 Module Documentation Publishing + +The website publishes module documentation from Git submodules. +The main `/docs//` pages should match the latest released module package, not unreleased branch content. + +See [Module Documentation Publishing](module-documentation.html) for the submodule policy and docs-only exception rules. + ## 📚 Useful Material - GitHub's guide on [Contributing to Open Source](https://guides.github.com/activities/contributing-to-open-source/#pull-request) diff --git a/docs/Contributing/module-documentation.md b/docs/Contributing/module-documentation.md new file mode 100644 index 0000000..88b1c43 --- /dev/null +++ b/docs/Contributing/module-documentation.md @@ -0,0 +1,46 @@ +--- +layout: documentation +--- +# Module Documentation Publishing + +The public documentation under `/docs//` should describe the module version users can install from the PowerShell Gallery. + +## Release-aligned documentation + +The website consumes module documentation through Git submodules in `modules/`. +For normal updates, each module submodule should point at the latest released module tag. + +This keeps cmdlet documentation, examples, parameters, and behavior notes aligned with the package users get from `Install-Module`. +The website must not publish documentation from a module branch that contains unreleased or breaking changes as the main module documentation. + +Some legacy modules do not have release tags. +Do not treat an untagged submodule as release-aligned unless the module has no tags and the submodule commit is the explicit published documentation baseline for that module. + +## Docs-only exceptions + +A module submodule may point at a non-release commit only when the commit is compatible with the latest released package and changes documentation quality only. +Examples include typo fixes, formatting cleanup, broken-link fixes, and clarification of behavior that already exists in the released package. + +Do not use a docs-only exception for changes that describe new cmdlets, new parameters, changed outputs, changed compatibility behavior, or unreleased breaking changes. +Those changes require a module release before they appear under `/docs//`. + +When opening a website pull request for a docs-only submodule update, call this out in the title or body. +The next module release should include those documentation commits and move the website submodule back to a release tag. + +## Pull request checklist + +- Identify every module submodule moved by the PR. +- For each moved active module, record the target tag or explain why no tag exists. +- If the target is not a tag, state whether it is a docs-only exception or a no-tags baseline. +- Confirm that the published docs do not describe unreleased behavior. +- Run `bash .github/scripts/check-module-submodules.sh` to verify active module submodules are release-aligned or explicitly excepted. +- Run the website build before requesting review. + +The Pages workflow runs the same submodule check before building the site. +The check fails when an active module submodule points at an untagged commit unless that module has an explicit no-tags baseline exception. +For a docs-only exception, add a narrow commit-specific exception in `.github/scripts/check-module-submodules.sh` and explain it in the pull request body before requesting review. + +## Preview documentation + +If unreleased documentation is useful before a release, publish it under a clearly labeled preview location instead of the main `/docs//` path. +Preview documentation must make clear that it may not match the latest PowerShell Gallery package. diff --git a/docs/Contributing/submitting-a-pr.md b/docs/Contributing/submitting-a-pr.md index 34d60d2..00ca317 100644 --- a/docs/Contributing/submitting-a-pr.md +++ b/docs/Contributing/submitting-a-pr.md @@ -26,16 +26,14 @@ Use that flow as your baseline, then apply repo-specific setup and validation de | Project | Guide | | ----------------------------- | ------------------------------------------------------------------------------------------- | -| **AtlassianPS** | | | **AtlassianPS.Configuration** | | | **AtlassianPS.github.io** | This docs section (you are here) | -| **BitbucketPS** | | | **ConfluencePS** | | -| **HipChatPS** | | | **JiraAgilePS** | | | **JiraPS** ⭐ | | As other modules adopt the JiraPS standard, their README links above will be replaced with `CONTRIBUTING.md`. +Legacy modules such as `AtlassianPS`, `BitbucketPS`, and `HipChatPS` are not active documentation targets on this website. ## 🧰 Setup From 5ea10883595e1b90b663f306f0c18dfd95a6f79a Mon Sep 17 00:00:00 2001 From: Oliver Lipkau Date: Sun, 24 May 2026 21:28:57 +0200 Subject: [PATCH 3/4] Use module root for about navigation --- _includes/sidenav.html | 7 ++++++- _layouts/documentation.html | 6 +++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/_includes/sidenav.html b/_includes/sidenav.html index f38ab34..f373e41 100644 --- a/_includes/sidenav.html +++ b/_includes/sidenav.html @@ -14,8 +14,13 @@ {% if module.groups %} {% for group in module.groups %} {% capture groupPath %}/{{ module.path }}/{{ group | downcase }}{% endcapture%} + {% if group == "About" %} + {% capture groupLink %}/{{ module.path }}{% endcapture %} + {% else %} + {% capture groupLink %}{{ groupPath }}{% endcapture %} + {% endif %}
- {{group}} + {{group}}
    diff --git a/_layouts/documentation.html b/_layouts/documentation.html index 53aafd3..b22bdd5 100644 --- a/_layouts/documentation.html +++ b/_layouts/documentation.html @@ -76,7 +76,11 @@ All Modules {% endif %} {% if bc_groupName %} - {{ bc_groupName }} + {% if bc_groupName == "About" %} + {{ bc_groupName }} + {% else %} + {{ bc_groupName }} + {% endif %} {% else %} Common {% endif %} From 40977f6acdabadcb51baeeb80a0e7bd7da042b0b Mon Sep 17 00:00:00 2001 From: Oliver Lipkau Date: Sun, 24 May 2026 21:39:00 +0200 Subject: [PATCH 4/4] Update JiraAgilePS docs baseline --- modules/JiraAgilePS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/JiraAgilePS b/modules/JiraAgilePS index 346ac95..ce33340 160000 --- a/modules/JiraAgilePS +++ b/modules/JiraAgilePS @@ -1 +1 @@ -Subproject commit 346ac9506b26dc48bc24d28c6e0272a13af5e1e7 +Subproject commit ce3334097716b9dda3e3ed91afba809e2b1773ef