Align module documentation publishing

.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"

.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:

Gemfile

@@ -2,3 +2,4 @@ source 'https://rubygems.org'
 gem 'github-pages', group: :jekyll_plugins
 
 gem "webrick", "~> 1.8"
+gem "logger", "~> 1.6"

_data/index/modules.yml

@@ -1,7 +1,4 @@
-# projects section data
-# - name: BitbucketPS
 - name: ConfluencePS
-# - name: HipChatPS
 - name: JiraAgilePS
 - name: JiraPS
 - name: AtlassianPS.Configuration

_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

_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

_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 %}
     <div class="bd-toc-item{% if page.url contains groupName %} active{% endif %}">
-        <a class="bd-toc-link" href="{{ groupPath }}">{{group}}</a>
+        <a class="bd-toc-link" href="{{ groupLink }}">{{group}}</a>
 
         <ul class="nav bd-sidenav">
 

_layouts/documentation.html

@@ -76,7 +76,11 @@
                     <a href="#" class="btn btn-default hide" data-algolia="lvl0">All Modules</a>
                 {% endif %}
                 {% if bc_groupName %}
-                    <a href="/docs/{{ bc_moduleName }}/{{ cl_groupName }}" class="btn btn-default" data-algolia="lvl1">{{ bc_groupName }}</a>
+                    {% if bc_groupName == "About" %}
+                        <a href="/docs/{{ bc_moduleName }}" class="btn btn-default" data-algolia="lvl1">{{ bc_groupName }}</a>
+                    {% else %}
+                        <a href="/docs/{{ bc_moduleName }}/{{ cl_groupName }}" class="btn btn-default" data-algolia="lvl1">{{ bc_groupName }}</a>
+                    {% endif %}
                 {% else %}
                     <a href="#" class="btn btn-default hide" data-algolia="lvl1">Common</a>
                 {% endif %}

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**               | <https://github.com/AtlassianPS/AtlassianPS/issues/new>               | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/AtlassianPS.svg?maxAge=2592000)](https://github.com/AtlassianPS/AtlassianPS/issues)                             |
 | **AtlassianPS.Configuration** | <https://github.com/AtlassianPS/AtlassianPS.Configuration/issues/new> | [![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**     | <https://github.com/AtlassianPS/AtlassianPS.github.io/issues/new>     | [![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**               | <https://github.com/AtlassianPS/BitbucketPS/issues/new>               | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/BitbucketPS.svg?maxAge=2592000)](https://github.com/AtlassianPS/BitbucketPS/issues)                             |
 | **ConfluencePS**              | <https://github.com/AtlassianPS/ConfluencePS/issues/new>              | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/ConfluencePS.svg?maxAge=2592000)](https://github.com/AtlassianPS/ConfluencePS/issues)                           |
-| **HipchatPS**                 | <https://github.com/AtlassianPS/HipchatPS/issues/new>                 | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/HipchatPS.svg?maxAge=2592000)](https://github.com/AtlassianPS/HipchatPS/issues)                                 |
 | **JiraAgilePS**               | <https://github.com/AtlassianPS/JiraAgilePS/issues/new>               | [![Open Issues](https://img.shields.io/github/issues-raw/AtlassianPS/JiraAgilePS.svg?maxAge=2592000)](https://github.com/AtlassianPS/JiraAgilePS/issues)                             |
 | **JiraPS**                    | <https://github.com/AtlassianPS/JiraPS/issues/new>                    | [![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/<Module>/` 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)

docs/Contributing/module-documentation.md

@@ -0,0 +1,46 @@
+---
+layout: documentation
+---
+# Module Documentation Publishing
+
+The public documentation under `/docs/<Module>/` 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/<Module>/`.
+
+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/<Module>/` path.
+Preview documentation must make clear that it may not match the latest PowerShell Gallery package.

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**               | <https://github.com/AtlassianPS/AtlassianPS/blob/master/README.md>                         |
 | **AtlassianPS.Configuration** | <https://github.com/AtlassianPS/AtlassianPS.Configuration/blob/master/README.md>           |
 | **AtlassianPS.github.io**     | This docs section (you are here)                                                            |
-| **BitbucketPS**               | <https://github.com/AtlassianPS/BitbucketPS/blob/master/README.md>                         |
 | **ConfluencePS**              | <https://github.com/AtlassianPS/ConfluencePS/blob/master/README.md>                        |
-| **HipChatPS**                 | <https://github.com/AtlassianPS/HipChatPS/blob/master/README.md>                           |
 | **JiraAgilePS**               | <https://github.com/AtlassianPS/JiraAgilePS/blob/master/README.md>                         |
 | **JiraPS** ⭐                 | <https://github.com/AtlassianPS/JiraPS/blob/master/CONTRIBUTING.md>                        |
 
 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