From ea2eceb7787ba98e9438eb75785caa30986995c7 Mon Sep 17 00:00:00 2001 From: Oliver Lipkau Date: Tue, 19 May 2026 00:32:15 +0200 Subject: [PATCH 1/7] Refresh docs contributor journey and hygiene checks Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/docs-hygiene.yml | 103 ++++++++ .lycheeignore | 1 + docs/Contributing/index.md | 145 +++--------- docs/Contributing/our-guidelines.md | 142 +++-------- docs/Contributing/submitting-a-pr.md | 237 ++++++------------- docs/Contributing/writing-functions.md | 32 ++- docs/Contributing/writing-tests.md | 29 ++- docs/Gallery/InitializeEnvironment.md | 14 +- docs/Gallery/SQLServerUpdatesToJIRAIssues.md | 2 +- docs/Gallery/UploadFromJson.md | 6 +- docs/Gallery/WatchIssues.md | 4 +- docs/Gallery/_sample.md | 20 +- docs/Gallery/index.md | 21 +- 13 files changed, 331 insertions(+), 425 deletions(-) create mode 100644 .github/workflows/docs-hygiene.yml create mode 100644 .lycheeignore diff --git a/.github/workflows/docs-hygiene.yml b/.github/workflows/docs-hygiene.yml new file mode 100644 index 0000000..a9724df --- /dev/null +++ b/.github/workflows/docs-hygiene.yml @@ -0,0 +1,103 @@ +name: Docs hygiene + +on: + workflow_dispatch: + push: + branches: [master] + paths: + - "docs/**" + - "_data/**" + - "assets/**" + - "_layouts/**" + - "_includes/**" + - ".github/workflows/docs-hygiene.yml" + pull_request: + branches: [master] + paths: + - "docs/**" + - "_data/**" + - "assets/**" + - "_layouts/**" + - "_includes/**" + - ".github/workflows/docs-hygiene.yml" + +permissions: + contents: read + +jobs: + content-check: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Guard against stale placeholder docs text + run: | + set -euo pipefail + + if grep -RInE "THIS PAGE IS IN WORK|This page describes:" docs; then + echo "Found placeholder docs text. Please replace with real content." + exit 1 + fi + + if grep -RInE 'git checkout develop|out of `develop`|merged into the `develop` branch' docs/Contributing; then + echo "Found outdated branch guidance that still references develop." + exit 1 + fi + + - name: Validate AtlassianPS repository guide links + env: + GITHUB_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + + mapfile -t urls < <(grep -Eo 'https://github\.com/AtlassianPS/[A-Za-z0-9._-]+/blob/master/[A-Za-z0-9._/-]+' docs/Contributing/submitting-a-pr.md | sort -u) + + if [ "${#urls[@]}" -eq 0 ]; then + echo "No AtlassianPS repository guide links found in docs/Contributing/submitting-a-pr.md." + exit 1 + fi + + for url in "${urls[@]}"; do + slug="${url#https://github.com/AtlassianPS/}" + repo="${slug%%/*}" + file_path="${slug#${repo}/blob/master/}" + api_url="https://api.github.com/repos/AtlassianPS/${repo}/contents/${file_path}?ref=master" + + status="$(curl -sS -o /dev/null -w '%{http_code}' \ + -H 'Accept: application/vnd.github+json' \ + -H "Authorization: Bearer ${GITHUB_TOKEN}" \ + "${api_url}")" + + if [ "${status}" -ne 200 ]; then + echo "Broken repository guide link: ${url} (HTTP ${status})" + exit 1 + fi + + echo "OK: ${url}" + done + + local-link-check: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: "3.3" + bundler-cache: true + + - name: Build Jekyll site + run: bundle exec jekyll build --baseurl "" + env: + JEKYLL_ENV: production + + - name: Check local docs links and anchors + uses: lycheeverse/lychee-action@v2 + with: + args: --offline --no-progress --root-dir _site '_site/docs/Contributing/**/*.html' '_site/docs/Gallery/**/*.html' + fail: true diff --git a/.lycheeignore b/.lycheeignore new file mode 100644 index 0000000..9840f94 --- /dev/null +++ b/.lycheeignore @@ -0,0 +1 @@ +file://.*/_site/module/JiraAgilePS/?$ diff --git a/docs/Contributing/index.md b/docs/Contributing/index.md index e14b2af..2e4eb0c 100644 --- a/docs/Contributing/index.md +++ b/docs/Contributing/index.md @@ -3,82 +3,32 @@ layout: documentation --- # Contributing to AtlassianPS -## Overview - -This page describes: - -- [Contributing to AtlassianPS](#contributing-to-atlassianps) - - [Overview](#overview) - - [Thank you!](#thank-you) - - [Report anything that is not working as expected](#report-anything-that-is-not-working-as-expected) - - [Question current methods and solutions](#question-current-methods-and-solutions) - - [Write documentation](#write-documentation) - - [Fix errors](#fix-errors) - - [Contribute code](#contribute-code) - - [How To Report An Issue](#how-to-report-an-issue) - - [How To Submit Code Changes](#how-to-submit-code-changes) - - [Development Container](#development-container) - - [Working locally (in VS Code)](#working-locally-in-vs-code) - - [Using Github Codespace](#using-github-codespace) - - [Our Guidelines](#our-guidelines) - - [Useful Material](#useful-material) - -## Thank you! - -We sincerely wish to thank you for donating your time to the AtlassianPS projects. -The quality of our projects increase with every contribution. - -> One thing I can't stress enough: -> you do **not** need to be an expert coder to contribute. -> Minor bug fixes and documentation corrections are just as valuable to the goals of the projects. -> _All contributors, independent of the size of the contribution, are listed on our [Homepage](https://atlassianps.org/#people)._ +Thank you for helping improve AtlassianPS. ---- - -There are several ways to contribute: - -### Report anything that is not working as expected - -It is impossible to think of every way the modules are used. - -_see [submitting an issue]_ - -### Question current methods and solutions - -It is likely that a different way to solve a problem was not considered. - -_see [submitting an issue]_ -_chat with us on [AtlassianPS.Discord]_ - -### Write documentation +You do **not** need to be an expert to contribute. Small fixes, typo corrections, and docs improvements are all valuable. +Every contribution matters, and we are glad you are here. -Writing useful and easy-to-read documentation is hard. -Any help with documentation is valuable, even fixing typos. +## ๐Ÿš€ Start here -_see [submitting code changes]_ +- Want to report a problem or suggest an idea? See [How To Report An Issue](#-how-to-report-an-issue). +- Want to submit changes? See [How To Submit Code Changes](#-how-to-submit-code-changes). +- Want coding standards? Read [Our Guidelines](our-guidelines.html). -### Fix errors +## ๐Ÿค Common ways to contribute -If you know how to fix a problem that you found, sending a Pull Request will simplify the process. +- Report bugs or unclear behavior. +- Improve documentation. +- Fix defects you can reproduce. +- Add small quality-of-life enhancements. +- Contribute larger features. -_see [submitting code changes]_ -_see [our guidelines]_ +> **Tip:** Not sure where to begin? Small docs improvements are a great first contribution. -### Contribute code +## ๐Ÿž How To Report An Issue -There is _a lot_ that can be added to our projects. Any help is welcome. +When you notice something that could be improved, tell us by creating an issue. -_see [submitting code changes]_ -_see [our guidelines]_ -_see [investigating Atlassian APIs]_ - -## How To Report An Issue - -When you notice something that could be improved, -tell us by creating an issue. -GitHub makes this easy. - -Each of our projects has an _Issuetracker_ where you can report your findings. +Each of our projects has an _issue tracker_ where you can report your findings. | Project | Link | # of open issues | | ----------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -87,56 +37,37 @@ Each of our projects has an _Issuetracker_ where you can report your findings. | **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/HipchatPSPS.svg?maxAge=2592000)](https://github.com/AtlassianPS/HipchatPS/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) | -New issues are created using a template which includes pre-defined text for reporting coding exceptions. -If your issue is not related to a coding error (e.g. you are suggesting a new feature), please modify the content to suit your needs. - -**Prior to creating a new issue, please search the issues to determine if a similar issue has already been created.** -**If one has, add any relevant comments to the issue's discussion.** - -## How To Submit Code Changes +Before creating a new issue, please search open issues first. +If a similar issue already exists, add your details there. -No matter if you are fixing a typo or if you wrote a fully-functioning feature for a project: -**You will have to send your code to `AtlassianPS`** +## ๐Ÿ” How To Submit Code Changes -> The possibilities of what our projects can do is ever growing (as Atlassian also makes changes to the API). -> Therefore it is very unlikely for our project to ever be _feature complete_. -> The only chance we have to keep up with the changes, is by having as many people involved as possible. -> We appreciate the help ๐Ÿ˜Š +No matter if you are fixing a typo or shipping a new feature, changes are submitted through a Pull Request. -This makes sense, as it would be impossible to manage user permissions in all of the project for all of the users. -Therefore, everyone who want to make changes to the code must make a copy of the repository into his GitHub account (aka [forking](https://help.github.com/articles/fork-a-repo/)). +Start with **[Submitting A PR](submitting-a-pr.html)** for the full flow. -With a copy of the code in a location where you are allowed to make changes to, you get to work. - -When you are finished, you will send your changes to the original project (aka [Pull Request](https://help.github.com/articles/about-pull-requests/)). -It will be reviewed and, when approved, merged. - -There is a bit more to take into account when submitting code to the projects. -You can read all about it here: **[Submitting A PR]**. - -### Development Container +### ๐Ÿงฐ Development Container Our repository includes a ["Dev Container"](https://containers.dev/) / GitHub Codespaces development container. -> **What are Development Containers?** -> A development container (or dev container for short) allows you to use +> **Note:** A development container (or dev container for short) allows you to use > a container as a full-featured development environment. > It can be used to run an application, to separate tools, libraries, > or runtimes needed for working with a codebase, > and to aid in continuous integration and testing. -You can use the devcontainer to spin up a fine tuned development environment with +You can use the devcontainer to spin up a fine-tuned development environment with everything you need for working on AtlassianPS projects. -You can use the devcontainer in your favorite edit or github codespace. +You can use the devcontainer in your favorite editor or GitHub Codespace. #### Working locally (in VS Code) -You can use the bellow links to get started. +You can use the links below to get started. The links will trigger VS Code to automatically install the Dev Containers extension if needed, clone the source code into a container volume, and spin up a dev container for use. @@ -148,30 +79,22 @@ clone the source code into a container volume, and spin up a dev container for u - [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) -#### Using Github Codespace +#### Using GitHub Codespace -Github allows you to spin up a virtual editor ("VS Code in your browser"). +GitHub allows you to spin up a virtual editor ("VS Code in your browser"). You can create your own codespace by navigating to -or by using the "Code" button in the repository itself, as shown bellow. +or by using the "Code" button in the repository itself, as shown below. ![Create Codespace In Repository](../../assets/img/create_github_codespace.png) -## Our Guidelines - -We strive for making the process of contributing as easy as possible. -However, having good documentation, follow some best practices and keeping the code aligned is crucial for a high quality of the projects. +## ๐Ÿ“ Our Guidelines -When contributing to the code, please follow [Our Guidelines](our-guidelines.html). +Please follow [Our Guidelines](our-guidelines.html) when contributing code or docs. -## Useful Material +## ๐Ÿ“š Useful Material - GitHub's guide on [Contributing to Open Source](https://guides.github.com/activities/contributing-to-open-source/#pull-request) - [GitHub Flow Guide](https://guides.github.com/introduction/flow/): step-by-step instructions of GitHub flow. [AtlassianPS.Discord]: https://atlassianps.org/contact/ - [submitting an issue]: #how-to-report-an-issue - [submitting code changes]: #how-to-submit-code-changes - [our guidelines]: #our-guidelines - [investigating Atlassian APIs]: #todo - [Submitting A PR]: submitting-a-pr.html diff --git a/docs/Contributing/our-guidelines.md b/docs/Contributing/our-guidelines.md index 5e37151..c5e72e6 100644 --- a/docs/Contributing/our-guidelines.md +++ b/docs/Contributing/our-guidelines.md @@ -3,138 +3,62 @@ layout: documentation --- # Our Guidelines -## Overview +These guidelines keep contributions consistent and review-friendly across AtlassianPS projects. +Think of them as guardrails that make collaboration easier. -This page describes: +## 1) ๐Ÿง  Prefer clear code over clever code -- [Our Guidelines](#our-guidelines) - - [Overview](#overview) - - [Code Formatting and Conventions](#code-formatting-and-conventions) - - [Formatting](#formatting) - - [Templates](#templates) - - [Variable Naming](#variable-naming) - - [Function Naming](#function-naming) - - [Splatting](#splatting) - - [Aliases](#aliases) - - [In-code Documentation](#in-code-documentation) - - [Code Separation and File Naming](#code-separation-and-file-naming) - - [Strive for 100% Code Coverage by Tests](#strive-for-100-code-coverage-by-tests) - - [Document as You Go](#document-as-you-go) - - [Changes To the Build System](#changes-to-the-build-system) +- Use descriptive names. +- Keep functions focused. +- Avoid hidden side effects. +- Refactor when comments are needed to explain basic flow. -## Code Formatting and Conventions +## 2) ๐Ÿงฉ Follow PowerShell conventions -### Formatting +- Use approved `Verb-Noun` function names. +- Use PascalCase for parameters and public members. +- Use camelCase for local variables. +- Expand aliases before submitting a PR. -All code must be properly formatted for a Pull Request (PR) to be merged. -For examples of formatting, take a look around the public functions of the projects. +## 3) ๐Ÿ—‚๏ธ Keep files and structure predictable -If you are using VS Code, the project is already configured to help you with that. +- One function/class/enum per file. +- Match file names to the function/class/enum name. +- Keep public and private code separated according to repository structure. -### Templates +## 4) ๐Ÿ“Œ Use splatting for readability -_No templates yet._ -_Fill in when available._ - -### Variable Naming - -The naming convention asks for Pascal Case for all parameters, function nouns, method names, property names, field names, etc. -Local variables created within a function should be in Camel Case. - -Example: - -```powershell -$GlobalVariable = "this is global" -function Get-GlobalVariable { - param( - $InputObject, - $Filter - ) - $localVariable = "this is local" - $global:GlobalVariable -} -``` - -Additional Information: - -- [More about special case styles](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) - -### Function Naming - -Functions should use proper `Verb-Noun` names even for private functions -and only use [Approved Verbs](https://msdn.microsoft.com/en-us/library/ms714428(v=vs.85).aspx). - -### Splatting - -Use [splatting] whenever a command has 3 or more parameters. Use the `$params` variable for splatting. -If you need to splat more than one command in a pipeline use `$Params` (e.g. `$ParamsGetContent` ) for each command in the pipeline. +Use [splatting] when a command has multiple parameters, especially in pipelines. ```powershell -# Single command -$Params = @{ +$paramsGetWidget = @{ Name = 'Widget1' Id = '5ABCD98727658' - Type = 'Custom' } -Get-Widget @Params -# Multi-command pipeline -$ParamsAddWidget = @{ - Name = 'Widget1' - Id = '5ABCD98727658' - Type = 'Custom' -} -$ParamsSetWidget = @{ +$paramsSetWidget = @{ Height = 10 Width = 20 - Depth = 3 } -Add-Widget @ParamsAddWidget | Set-Widget @ParamsSetWidget -``` - -### Aliases - -Expand all aliases prior to a PR. -No aliases are permitted, including `Sort`. -The PSAnalyzer tests should detect this and issue a failure. - -### In-code Documentation -Limit in-code comments and documentation. -If you are using full, command names and PowerShell "best practices", the code should be fairly self-documenting. -Only use comments when doing something that is out of the norm or obscure. -If you feel you need to comment the code, you likely need to refactor it. - -## Code Separation and File Naming - -- all functions (public and private), classes, and enums should be defined in separate files and organized according to their category. -- do not define more than one function, class, or enum per file. -- do not create nested functions (use separate private functions instead). -- the filename should match the function or enum name. - -## Strive for 100% Code Coverage by Tests - -This project strives to be as close to 100% code coverage as possible. -If you are submitting a new function (public or private), -the PR will not be merged until a unit test has been added that tests all available code paths for the function. -The same goes for classes. -If you extend the functionality of an existing feature, please add the tests that describe the changes. - -## Document as You Go +Get-Widget @paramsGetWidget | Set-Widget @paramsSetWidget +``` -The documentation of a project is located in the `/docs/` folder and is the source of truth for all documentation. +## 5) ๐Ÿงช Treat tests and docs as part of the change -We realize documentation is a boring part of coding, but it is a necessary evil. -This is not something that can be thrown over the wall unless we gain some dedicated documentation contributors. -The only way to keep this project properly documented is to do it as we go and not after the fact. +- Add or update tests for behavior changes. +- Update user-facing documentation for user-facing changes. +- Do not ship code changes without matching validation/docs updates. -Any code submission will be checked for documentation according to its changes. +## 6) ๐Ÿ’ฌ Keep comments intentional -## Changes To the Build System +Comments should explain: -_This chapter must describe how to make changes and test them against AppVeyor/Travis._ +- constraints and edge cases +- non-obvious workarounds +- design intent when structure alone is not enough -_Maybe a page dedicated to this topic might be in order._ +If a comment only explains what the line already says, remove it. - [splatting]: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting +[splatting]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_splatting diff --git a/docs/Contributing/submitting-a-pr.md b/docs/Contributing/submitting-a-pr.md index ce981df..34d60d2 100644 --- a/docs/Contributing/submitting-a-pr.md +++ b/docs/Contributing/submitting-a-pr.md @@ -3,194 +3,109 @@ layout: documentation --- # Submitting A Pull Request -## Overview - -This page describes: - -- [Submitting A Pull Request](#submitting-a-pull-request) - - [Overview](#overview) - - [TL;DR](#tldr) - - [The Setup](#the-setup) - - [New to Git(Hub)?](#new-to-github) - - [Tooling](#tooling) - - [Getting Started](#getting-started) - - [Find Something To Contribute To](#find-something-to-contribute-to) - - [Forking And Branching](#forking-and-branching) - - [Making Changes](#making-changes) - - [Getting Work Done](#getting-work-done) - - [Documenting Your Work](#documenting-your-work) - - [Making Sure All Is Working](#making-sure-all-is-working) - - [Sending Your Changes](#sending-your-changes) - - [Send A Pull Request](#send-a-pull-request) - - [What Happens Next?](#what-happens-next) - -## TL;DR - -Here is a list for project specific instructions. -These are more technical - pretty much what would have to be executed in the console. - -| Project | Instructions | -| ----------------------------- | -------------------------------------------------------------------------------------- | -| **AtlassianPS** | | -| **AtlassianPS.Configuration** | | -| **AtlassianPS.github.io** | | -| **BitbucketPS** | | -| **ConfluencePS** | | -| **HipchatPS** | | -| **JiraAgilePS** | | -| **JiraPS** | | - -## The Setup - -### New to Git(Hub)? - -- Make sure you have a [GitHub account](https://github.com/signup/free). -- Learning Git: - - GitHub Help: [Good Resources for Learning Git and GitHub][good-git-resources]. - - [Git Basics](https://github.com/PowerShell/PowerShell/blob/master/docs/git/basics.md): install and getting started. - -### Tooling - -To make changes to the code or documentation and send it as a Pull Request, only one tool is required: - -- **[Git]** -_There are many different ways to install Git._ -_Please google how to install it on your OS._ -- **PowerShell** -_Any version works._ -_If you are using version 3 or 4, the `PowerShellGet` module must be installed._ -- **[InvokeBuild]** - -_Additional required modules are installed when `Invoke-Build` is called._ - -There are more tools that are not _required_, but will make life much easier. -Such as: - -| Tool | Description | -| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Graphic Interfaces for Git](https://git-scm.com/downloads/guis) | _Git can get messy. A nice UI can be helpful. This page contains some for you to use._ | -| [Visual Studio Code] | _This is the editor of choice for working with Powershell. The project contains settings to make life easier._ | -| [PowerShell Extension for VSCode] | _This extension provides rich PowerShell language support for Visual Studio Code. Now you can write and debug PowerShell scripts using the excellent IDE-like interface that Visual Studio Code provides._ | -| [Plaster Module] | _Plaster is a template-based file and project generator written in PowerShell._ | -| [Pester Module] | _Build Automation in PowerShell. Will be installed as a dependency with `Invoke-Build`._ | -| [PlatyPS] | _Write PowerShell External Help in Markdown._ | - -## Getting Started - -### Find Something To Contribute To - -If you are interested in contributing and have nothing specific in mind, -we are looking for help here: [Issue that are "Up-For-Grabs"](https://github.com/issues?utf8=โœ“&q=is%3Aopen+user%3AAtlassianPS+label%3Aup-for-grabs). - -### Forking And Branching - -GitHub fosters collaboration through the notion of [pull requests][using-prs]. -On GitHub, anyone can [fork][fork-a-repo] an existing repository -into their own user account, where they can make private changes to their fork. - -Once you have your own version of the project, you should: - -- Clone your version of the project to your computer -_Here is how: [Cloning a Repository](https://help.github.com/articles/cloning-a-repository/)._ - -** ```powershell - git clone https://github.com//.git - ```** - -- Create a new branch for your changes -_You should make the changes in a branch for tracking them._ -_You should also create your own branch out of `develop`._ -_You can read more here: [Git Flow Guide](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)._ - - ```powershell - cd - git checkout develop - git checkout -b - ``` +Use this page as a practical checklist for contributing to any AtlassianPS repository. +If this is your first PR, you are in the right place. -Additional references: +> **Tip:** Start small if you want to. A focused PR is often the fastest path to a successful review. + +## โœ… Quick checklist + +1. Pick an issue (or open one first). +2. Fork the target repository. +3. Create a feature branch from `master`. +4. Implement the change (code + tests + docs where needed). +5. Run the repository validation steps. +6. Open a Pull Request to `AtlassianPS/:master`. + +No stress if you do not get everything perfect on the first try. Reviews are collaborative. -- GitHub's guide on [forking](https://guides.github.com/activities/forking/) +## ๐Ÿงญ Project-specific contribution guides -## Making Changes +JiraPS is our current gold standard for contribution guidance. +Use that flow as your baseline, then apply repo-specific setup and validation details from each project's current guide. -### Getting Work Done +| Project | Guide | +| ----------------------------- | ------------------------------------------------------------------------------------------- | +| **AtlassianPS** | | +| **AtlassianPS.Configuration** | | +| **AtlassianPS.github.io** | This docs section (you are here) | +| **BitbucketPS** | | +| **ConfluencePS** | | +| **HipChatPS** | | +| **JiraAgilePS** | | +| **JiraPS** โญ | | -We do not impose a specific way to write code. +As other modules adopt the JiraPS standard, their README links above will be replaced with `CONTRIBUTING.md`. -However, there are some [Guidelines](our-guidelines.html) which should be followed at all times. +## ๐Ÿงฐ Setup -The checklist when creating the Pull Request will look something like this: +### Required tools -> **Types of changes:** -> -> - [ ] Bug fix (non-breaking change which fixes an issue) -> - [ ] New feature (non-breaking change which adds functionality) -> - [ ] Breaking change (fix or feature that would cause existing functionality to change) -> **Checklist:** -> - [ ] My code follows the code style of this project. -> - [ ] I have added Pester Tests that describe what my changes should do. -> - [ ] I have updated the documentation accordingly. +- [Git](https://git-scm.com) +- PowerShell +- Repository-specific tooling described in each project guide above -### Documenting Your Work +### Helpful tools -In general, PowerShell is verbose in a way that the code explains what it does. -So, minimal code documentation is needed. +- [Visual Studio Code](https://code.visualstudio.com) +- [PowerShell extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell) +- [Git GUIs](https://git-scm.com/downloads/guis) -When code is not easy to read or requires more extensive explaining (such as workarounds), -use comments to explain what it does to make it more readable for others. +## ๐ŸŒฟ Forking and branching -All parts of the code that affect user interaction are expected to have detailed documentation. -This includes (but is not limited to) _Functions_, _Parameters_ and _Output Types_. +```powershell +git clone https://github.com//.git +cd +git checkout master +git checkout -b +``` -It is also expected that the tests that describe the functionality are either updated or created, if the functionality is new. +Keep your branch focused on one change set. Small PRs are easier to review and merge. -Additional material: +## ๐Ÿ› ๏ธ Implementation expectations + +- Follow [Our Guidelines](our-guidelines.html). +- Update tests when behavior changes. +- Update docs for user-facing changes. +- Keep commits scoped and readable. + +Additional references: - [How to write a function](writing-functions.html) -- [How to write good tests](writing-tests.html) +- [How to write tests](writing-tests.html) + +## ๐Ÿงช Validation -### Making Sure All Is Working +Run the validation commands defined by the target repository before opening a PR. -The projects have several tests to ensure everything is working as expected. -_The tests are all in the `/Tests/` folder._ +> **Important:** Always run the repository's validation commands before opening or updating your PR. -The projects are set up so that running `Invoke-Build` will make sure the code is working as the tests describe. -**The command must be run from the root of the project.** +For `AtlassianPS.github.io`, run: -## Sending Your Changes +```bash +bundle exec jekyll build --baseurl "" +``` -### Send A Pull Request +## ๐Ÿ“ฌ Opening the Pull Request -When you are done _and all tests pass_, you can send the changes "upstream" (to the AtlassianPS project). +Open a PR from your fork branch to the upstream `master` branch. -Here is how you create the Pull Request: [Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/) +A strong PR description should include: -### What Happens Next? +- what changed +- why it changed +- how you validated it -Now our [maintainers](https://github.com/orgs/AtlassianPS/teams/maintainers) and [reviewers](https://github.com/orgs/AtlassianPS/teams/reviewers) will look over what you submitted. +## ๐Ÿค What happens next -To help them, the GitHub repositories will use [CI](https://en.wikipedia.org/wiki/Continuous_integration) jobs to run the tests and report if the submitted code is working as expected. +Maintainers and reviewers will review your PR and CI checks. -Every Pull Request must be approved after review and the reviewer(s) might: +You may be asked to: -- have some constructive feedback for your code and suggest optimizations (eg: adding `Write-Verbose` messages) -- request you to make specific changes before approving it (eg: adding tests) -- request changes to the documentation (eg: add a new _example_ to the function) -- push some changes to your code (eg: harmonize some code) -_By default, github grants "write" permissions to the reviewers to your fork._ -_You can disable this, if you wish._ +- adjust implementation details +- add or update tests +- update docs/examples -Once the reviewer approves your Pull Request, it will be merged into the `develop` branch and part of the next release. +Once approved, the PR is merged into `master`. - - [Pester Module]: https://github.com/pester/Pester - [Git]: https://git-scm.com - [Visual Studio Code]: https://code.visualstudio.com - [Plaster Module]: https://github.com/PowerShell/Plaster - [PowerShell Extension for VSCode]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell - [InvokeBuild]: https://github.com/nightroman/Invoke-Build - [PlatyPS]: https://github.com/PowerShell/platyPS - [using-prs]: https://help.github.com/articles/using-pull-requests/ - [fork-a-repo]: https://help.github.com/articles/fork-a-repo/ - [good-git-resources]: https://help.github.com/articles/good-resources-for-learning-git-and-github/ +If you get stuck at any point, open an issue and ask for guidance. diff --git a/docs/Contributing/writing-functions.md b/docs/Contributing/writing-functions.md index aef24a6..ecfc60d 100644 --- a/docs/Contributing/writing-functions.md +++ b/docs/Contributing/writing-functions.md @@ -3,15 +3,33 @@ layout: documentation --- # Writing Functions -**THIS PAGE IS IN WORK** +This page covers the baseline expectations for writing PowerShell functions in AtlassianPS projects. +Use it as a lightweight checklist, not a barrier. -## Overview +## ๐Ÿงฉ Public Functions -This page describes: +- Use approved `Verb-Noun` naming. +- Keep parameters explicit and discoverable. +- Provide clear output types and examples in docs. +- Favor readability over cleverness. +- Add or update tests for behavior changes. -* [Public Functions](#public-functions) -* [Private Functions](#private-functions) +Public command documentation should be updated in the repository's docs alongside code changes. -## Public Functions +## ๐Ÿ”’ Private Functions -## Private Functions +- Keep helpers focused on one responsibility. +- Give private functions intention-revealing names. +- Prefer composition over deeply nested logic. +- Avoid side effects where possible. +- Keep private helpers covered by unit tests through public behavior or direct tests (based on repo pattern). + +## โœ… Practical checklist + +> **Tip:** Prefer small, focused function changes. They are easier to test and review. + +- [ ] Function name follows project naming conventions. +- [ ] Parameters are validated and documented. +- [ ] Error paths are explicit and actionable. +- [ ] Tests cover happy path and key failure cases. +- [ ] User-facing docs are updated. diff --git a/docs/Contributing/writing-tests.md b/docs/Contributing/writing-tests.md index 2f354fb..5fc5970 100644 --- a/docs/Contributing/writing-tests.md +++ b/docs/Contributing/writing-tests.md @@ -3,15 +3,30 @@ layout: documentation --- # Writing Tests -**THIS PAGE IS IN WORK** +Tests are part of the change, not an optional follow-up. +Well-placed tests also make reviews and future refactors much easier. -## Overview +## โœ… Unit Tests -This page describes: +- Cover the expected success path. +- Cover key failure and validation paths. +- Keep tests deterministic and isolated. +- Name tests by behavior, not implementation details. -* [Unit Tests](#unit-tests) -* [Integration Tests](#integration-tests) +## ๐ŸŒ Integration Tests -## Unit Tests +Use integration tests when behavior depends on real API/server interaction. -## Integration Tests +- Keep credentials and environment setup out of committed code. +- Limit integration scope to high-value scenarios. +- Document prerequisites clearly in the repository. + +## ๐Ÿงช Practical checklist + +> **Caution:** Avoid brittle tests that depend on ordering, timing, or shared mutable state. + +- [ ] New behavior is tested. +- [ ] Existing behavior remains covered after refactors. +- [ ] Error handling has test coverage. +- [ ] Test names describe intent. +- [ ] Validation commands run clean before PR submission. diff --git a/docs/Gallery/InitializeEnvironment.md b/docs/Gallery/InitializeEnvironment.md index 479af29..f89fc1a 100644 --- a/docs/Gallery/InitializeEnvironment.md +++ b/docs/Gallery/InitializeEnvironment.md @@ -2,22 +2,22 @@ layout: galleryItem author: Lipkau title: Initialize Environment -synopsis: Setup the environment to work with JiraPS +synopsis: Set up the environment to work with JiraPS type: Working Script modules: - JiraPS -extras: +extras: - BetterCredentials --- ### Description This script will: -* install [BetterCredentials](https://github.com/Jaykul/BetterCredentials) -* install JiraPS -* import JiraPS into runtime -* load credentials -* authenticate with JIRA server +* Install [BetterCredentials](https://github.com/Jaykul/BetterCredentials) +* Install JiraPS +* Import JiraPS into runtime +* Load credentials +* Authenticate with JIRA server ![ScreenShot](screenshots/gallery_init-env.png) diff --git a/docs/Gallery/SQLServerUpdatesToJIRAIssues.md b/docs/Gallery/SQLServerUpdatesToJIRAIssues.md index e20542c..9c0cd5d 100644 --- a/docs/Gallery/SQLServerUpdatesToJIRAIssues.md +++ b/docs/Gallery/SQLServerUpdatesToJIRAIssues.md @@ -21,7 +21,7 @@ This script will do these things, in order: 1. Establish a connection with your company JIRA. 2. Fetch an RSS feed (in my script, the https://blogs.msdn.microsoft.com/sqlreleaseservices/feed/). 3. For each feed item in the feed: - 1. Extract useable information, like the feed item title, publishing date and link. + 1. Extract usable information, like the feed item title, publishing date, and link. 2. Check whether there already exists a JIRA issue with the same title/summary as the feed title. 3. If not, create the issue with a certain set of parameters. 4. Repeat for each feed item in the feed. diff --git a/docs/Gallery/UploadFromJson.md b/docs/Gallery/UploadFromJson.md index f08175b..2a07ef1 100644 --- a/docs/Gallery/UploadFromJson.md +++ b/docs/Gallery/UploadFromJson.md @@ -9,12 +9,12 @@ modules: --- ### Description -This script takes a Json file as input and updates all Issues in it. +This script takes a JSON file as input and updates all issues in it. -I have a colleague at work who writes HTML apps for managing due dates and sprint assignment of issues. +I have a colleague at work who writes HTML apps for managing due dates and sprint assignment of issues. He was unable to figure out how to upload the data back into Jira, as the server does not allow for CORS ajax requests. -So my workaround is: his HTML app dumps the results to JSON - and a scheduled job runs the following script that persists the changes to the issues on Jira. +So my workaround is: his HTML app dumps the results to JSON, and a scheduled job runs the following script that persists the changes to Jira issues. ![ScreenShot](screenshots/gallery_upload-changes.png) diff --git a/docs/Gallery/WatchIssues.md b/docs/Gallery/WatchIssues.md index 24a461e..be1eb4c 100644 --- a/docs/Gallery/WatchIssues.md +++ b/docs/Gallery/WatchIssues.md @@ -9,10 +9,10 @@ modules: --- ### Description -The following script allows one to search for as many Jira Issues as he wants +The following script lets you search as many Jira issues as needed with JQL and set predefined users as watchers of those issues. -_As a watchers of an issue, the user will receiver notifications for changes on the issue._ +_As a watcher of an issue, a user will receive notifications for changes on that issue._ ### Code diff --git a/docs/Gallery/_sample.md b/docs/Gallery/_sample.md index 4f9cdfa..831b1e9 100644 --- a/docs/Gallery/_sample.md +++ b/docs/Gallery/_sample.md @@ -1,23 +1,25 @@ --- layout: galleryItem -author: Jon Doe # Name/email of the author +author: Jon Doe # Name/email of the author title: Cool Script -synopsis: This cool script does stuff -type: [Idea | Working Script | Redacted Script] # Is this an idea or a working script? -modules: # List of module this entry uses +synopsis: One-line summary of what the script does +type: [Idea | Working Script | Redacted Script] # Choose one +modules: # List of modules this entry uses - BitbucketPS - ConfluencePS - HipChatPS - JiraPS -extras: # List of other resources/modules needed in script +extras: # List of other resources/modules needed - ... --- ### Description -A detailed description of what this script does -What problem does it try to solve? -What is the environment where this script is run in? +Add a short description of: + +- what the script does +- what problem it solves +- where/how it is expected to run ### Code -{% gist !!GIST ID!! %} +{% gist %} diff --git a/docs/Gallery/index.md b/docs/Gallery/index.md index a8a373a..f12ba41 100644 --- a/docs/Gallery/index.md +++ b/docs/Gallery/index.md @@ -4,16 +4,21 @@ layout: gallery # Gallery -This is a collection of ideas, scripts and intricate uses of the _AtlassianPS_ modules. +This is a collection of ideas, scripts, and practical uses of the _AtlassianPS_ modules. -## Contribute +## โœจ Contribute -This gallery can only be useful with as much input/collaboration as possible. So please consider submitting your ideas / code. +This gallery is best when many people contribute. Please consider submitting your ideas or code. -To submit your code, you need to [fork this repository](https://github.com/AtlassianPS/AtlassianPS.github.io/fork), -add your file to [the gallery](https://github.com/AtlassianPS/AtlassianPS.github.io/tree/master/docs/Gallery) -and [submit your changes as a Pull Request](https://github.com/AtlassianPS/AtlassianPS.github.io/compare). -**_You can find a detailed instruction [here](/docs/Contributing)._** +To submit your code: + +1. [Fork this repository](https://github.com/AtlassianPS/AtlassianPS.github.io/fork) +2. Add your file to [the gallery folder](https://github.com/AtlassianPS/AtlassianPS.github.io/tree/master/docs/Gallery) +3. [Open a Pull Request](https://github.com/AtlassianPS/AtlassianPS.github.io/compare) + +Detailed contribution guidance is available in [/docs/Contributing](/docs/Contributing). + +> **Tip:** Keep entries focused and practical. Short context plus working code is ideal. ### Disclaimer @@ -21,6 +26,6 @@ All the snippets in the gallery are licensed under the [MIT license](https://git > By adding your code to this gallery, you agree to this license. -## The Entries +## ๐Ÿ“š The Entries {% include galleryEntries.html %} From 96e953892494994e5a9fa0c92f11edadc4e1a72b Mon Sep 17 00:00:00 2001 From: Oliver Lipkau Date: Tue, 19 May 2026 08:45:31 +0200 Subject: [PATCH 2/7] Remove JiraAgilePS dead route and harden docs-hygiene triggers Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/docs-hygiene.yml | 2 ++ .lycheeignore | 1 - _data/modules.yml | 2 +- _data/navigation.yml | 3 ++- _includes/navigation.html | 7 ++++++- _includes/sections/modules.html | 8 +++++++- 6 files changed, 18 insertions(+), 5 deletions(-) delete mode 100644 .lycheeignore diff --git a/.github/workflows/docs-hygiene.yml b/.github/workflows/docs-hygiene.yml index a9724df..860719f 100644 --- a/.github/workflows/docs-hygiene.yml +++ b/.github/workflows/docs-hygiene.yml @@ -10,6 +10,7 @@ on: - "assets/**" - "_layouts/**" - "_includes/**" + - ".lycheeignore" - ".github/workflows/docs-hygiene.yml" pull_request: branches: [master] @@ -19,6 +20,7 @@ on: - "assets/**" - "_layouts/**" - "_includes/**" + - ".lycheeignore" - ".github/workflows/docs-hygiene.yml" permissions: diff --git a/.lycheeignore b/.lycheeignore deleted file mode 100644 index 9840f94..0000000 --- a/.lycheeignore +++ /dev/null @@ -1 +0,0 @@ -file://.*/_site/module/JiraAgilePS/?$ diff --git a/_data/modules.yml b/_data/modules.yml index 3668f48..611756c 100644 --- a/_data/modules.yml +++ b/_data/modules.yml @@ -13,7 +13,7 @@ - name: JiraAgilePS description: PowerShell module to interact with Jira's Agile plugin github: https://github.com/AtlassianPS/JiraAgilePS - path: /module/JiraAgilePS + path: https://github.com/AtlassianPS/JiraAgilePS - name: JiraPS description: PowerShell module to interact with Atlassian JIRA github: https://github.com/AtlassianPS/JiraPS diff --git a/_data/navigation.yml b/_data/navigation.yml index 312dc83..00d6f74 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -10,7 +10,8 @@ # - name: HipChatPS # path: module/HipChatPS - name: JiraAgilePS - path: module/JiraAgilePS + path: https://github.com/AtlassianPS/JiraAgilePS + target: _blank - name: JiraPS path: module/JiraPS - name: Documentation diff --git a/_includes/navigation.html b/_includes/navigation.html index 3133672..cc2b82c 100644 --- a/_includes/navigation.html +++ b/_includes/navigation.html @@ -27,7 +27,12 @@

  • {{ child.name }}
    • +
  • + {{ child.name }} +
    • {% endfor %} diff --git a/_includes/sections/modules.html b/_includes/sections/modules.html index c7a3fd4..60eb20c 100644 --- a/_includes/sections/modules.html +++ b/_includes/sections/modules.html @@ -5,8 +5,14 @@ repo="{{ module.name }}" class="module item col-10 col-md-5 ml-auto mr-auto" > + {% assign module_data = site.data.modules | where: "name", module.name | first %} + {% if module_data and module_data.path %} + {% assign module_link = module_data.path %} + {% else %} + {% assign module_link = "/module/" | append: module.name %} + {% endif %}
    - + Date: Tue, 19 May 2026 21:14:36 +0200 Subject: [PATCH 3/7] Simplify docs hygiene to build plus link check Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/docs-hygiene.yml | 54 +----------------------------- 1 file changed, 1 insertion(+), 53 deletions(-) diff --git a/.github/workflows/docs-hygiene.yml b/.github/workflows/docs-hygiene.yml index 860719f..3179e2a 100644 --- a/.github/workflows/docs-hygiene.yml +++ b/.github/workflows/docs-hygiene.yml @@ -27,63 +27,11 @@ permissions: contents: read jobs: - content-check: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Guard against stale placeholder docs text - run: | - set -euo pipefail - - if grep -RInE "THIS PAGE IS IN WORK|This page describes:" docs; then - echo "Found placeholder docs text. Please replace with real content." - exit 1 - fi - - if grep -RInE 'git checkout develop|out of `develop`|merged into the `develop` branch' docs/Contributing; then - echo "Found outdated branch guidance that still references develop." - exit 1 - fi - - - name: Validate AtlassianPS repository guide links - env: - GITHUB_TOKEN: ${{ github.token }} - run: | - set -euo pipefail - - mapfile -t urls < <(grep -Eo 'https://github\.com/AtlassianPS/[A-Za-z0-9._-]+/blob/master/[A-Za-z0-9._/-]+' docs/Contributing/submitting-a-pr.md | sort -u) - - if [ "${#urls[@]}" -eq 0 ]; then - echo "No AtlassianPS repository guide links found in docs/Contributing/submitting-a-pr.md." - exit 1 - fi - - for url in "${urls[@]}"; do - slug="${url#https://github.com/AtlassianPS/}" - repo="${slug%%/*}" - file_path="${slug#${repo}/blob/master/}" - api_url="https://api.github.com/repos/AtlassianPS/${repo}/contents/${file_path}?ref=master" - - status="$(curl -sS -o /dev/null -w '%{http_code}' \ - -H 'Accept: application/vnd.github+json' \ - -H "Authorization: Bearer ${GITHUB_TOKEN}" \ - "${api_url}")" - - if [ "${status}" -ne 200 ]; then - echo "Broken repository guide link: ${url} (HTTP ${status})" - exit 1 - fi - - echo "OK: ${url}" - done - local-link-check: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v6 with: submodules: recursive From e304d0a0c75763e5174c45ba27d9818d94163b09 Mon Sep 17 00:00:00 2001 From: Oliver Lipkau Date: Tue, 19 May 2026 21:54:38 +0200 Subject: [PATCH 4/7] Deduplicate docs-hygiene trigger paths Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/docs-hygiene.yml | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs-hygiene.yml b/.github/workflows/docs-hygiene.yml index 3179e2a..25d4e6a 100644 --- a/.github/workflows/docs-hygiene.yml +++ b/.github/workflows/docs-hygiene.yml @@ -4,7 +4,7 @@ on: workflow_dispatch: push: branches: [master] - paths: + paths: &docs_hygiene_paths - "docs/**" - "_data/**" - "assets/**" @@ -14,14 +14,7 @@ on: - ".github/workflows/docs-hygiene.yml" pull_request: branches: [master] - paths: - - "docs/**" - - "_data/**" - - "assets/**" - - "_layouts/**" - - "_includes/**" - - ".lycheeignore" - - ".github/workflows/docs-hygiene.yml" + paths: *docs_hygiene_paths permissions: contents: read From d9abab2ba6925a0bccf239777c6133f51c6ae03d Mon Sep 17 00:00:00 2001 From: Oliver Lipkau Date: Tue, 19 May 2026 22:04:27 +0200 Subject: [PATCH 5/7] Reduce docs workflow to build-only check Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/docs-hygiene.yml | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/.github/workflows/docs-hygiene.yml b/.github/workflows/docs-hygiene.yml index 25d4e6a..43bd584 100644 --- a/.github/workflows/docs-hygiene.yml +++ b/.github/workflows/docs-hygiene.yml @@ -1,26 +1,25 @@ -name: Docs hygiene +name: Docs build on: workflow_dispatch: push: branches: [master] - paths: &docs_hygiene_paths + paths: &docs_build_paths - "docs/**" - "_data/**" - "assets/**" - "_layouts/**" - "_includes/**" - - ".lycheeignore" - ".github/workflows/docs-hygiene.yml" pull_request: branches: [master] - paths: *docs_hygiene_paths + paths: *docs_build_paths permissions: contents: read jobs: - local-link-check: + build-docs: runs-on: ubuntu-latest steps: - name: Checkout @@ -38,9 +37,3 @@ jobs: run: bundle exec jekyll build --baseurl "" env: JEKYLL_ENV: production - - - name: Check local docs links and anchors - uses: lycheeverse/lychee-action@v2 - with: - args: --offline --no-progress --root-dir _site '_site/docs/Contributing/**/*.html' '_site/docs/Gallery/**/*.html' - fail: true From 41e3bec5d984bdff435abdfadfe303c8f29b039e Mon Sep 17 00:00:00 2001 From: Oliver Lipkau Date: Tue, 19 May 2026 22:07:30 +0200 Subject: [PATCH 6/7] Remove duplicate docs build workflow Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/docs-hygiene.yml | 39 ------------------------------ 1 file changed, 39 deletions(-) delete mode 100644 .github/workflows/docs-hygiene.yml diff --git a/.github/workflows/docs-hygiene.yml b/.github/workflows/docs-hygiene.yml deleted file mode 100644 index 43bd584..0000000 --- a/.github/workflows/docs-hygiene.yml +++ /dev/null @@ -1,39 +0,0 @@ -name: Docs build - -on: - workflow_dispatch: - push: - branches: [master] - paths: &docs_build_paths - - "docs/**" - - "_data/**" - - "assets/**" - - "_layouts/**" - - "_includes/**" - - ".github/workflows/docs-hygiene.yml" - pull_request: - branches: [master] - paths: *docs_build_paths - -permissions: - contents: read - -jobs: - build-docs: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v6 - with: - submodules: recursive - - - name: Setup Ruby - uses: ruby/setup-ruby@v1 - with: - ruby-version: "3.3" - bundler-cache: true - - - name: Build Jekyll site - run: bundle exec jekyll build --baseurl "" - env: - JEKYLL_ENV: production From a49263bfb8c81d5bd90c6ccfe5ecdc50596b474c Mon Sep 17 00:00:00 2001 From: Oliver Lipkau Date: Tue, 19 May 2026 22:22:41 +0200 Subject: [PATCH 7/7] Revert JiraAgilePS route workaround Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- _data/modules.yml | 2 +- _data/navigation.yml | 3 +-- _includes/navigation.html | 7 +------ _includes/sections/modules.html | 8 +------- 4 files changed, 4 insertions(+), 16 deletions(-) diff --git a/_data/modules.yml b/_data/modules.yml index 611756c..3668f48 100644 --- a/_data/modules.yml +++ b/_data/modules.yml @@ -13,7 +13,7 @@ - name: JiraAgilePS description: PowerShell module to interact with Jira's Agile plugin github: https://github.com/AtlassianPS/JiraAgilePS - path: https://github.com/AtlassianPS/JiraAgilePS + path: /module/JiraAgilePS - name: JiraPS description: PowerShell module to interact with Atlassian JIRA github: https://github.com/AtlassianPS/JiraPS diff --git a/_data/navigation.yml b/_data/navigation.yml index 00d6f74..312dc83 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -10,8 +10,7 @@ # - name: HipChatPS # path: module/HipChatPS - name: JiraAgilePS - path: https://github.com/AtlassianPS/JiraAgilePS - target: _blank + path: module/JiraAgilePS - name: JiraPS path: module/JiraPS - name: Documentation diff --git a/_includes/navigation.html b/_includes/navigation.html index cc2b82c..3133672 100644 --- a/_includes/navigation.html +++ b/_includes/navigation.html @@ -27,12 +27,7 @@

  • {{ child.name }} -
    • +
  • {{ child.name }}
    • {% endfor %} diff --git a/_includes/sections/modules.html b/_includes/sections/modules.html index 60eb20c..c7a3fd4 100644 --- a/_includes/sections/modules.html +++ b/_includes/sections/modules.html @@ -5,14 +5,8 @@ repo="{{ module.name }}" class="module item col-10 col-md-5 ml-auto mr-auto" > - {% assign module_data = site.data.modules | where: "name", module.name | first %} - {% if module_data and module_data.path %} - {% assign module_link = module_data.path %} - {% else %} - {% assign module_link = "/module/" | append: module.name %} - {% endif %}
    - +