Skip to content

Polish docs wording and reduce visual text density #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lipkau merged 7 commits into from
May 19, 2026
Merged

Polish docs wording and reduce visual text density #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ea2eceb
Refresh docs contributor journey and hygiene checks
lipkau May 18, 2026
96e9538
Remove JiraAgilePS dead route and harden docs-hygiene triggers
lipkau May 19, 2026
b2d0e86
Simplify docs hygiene to build plus link check
lipkau May 19, 2026
e304d0a
Deduplicate docs-hygiene trigger paths
lipkau May 19, 2026
d9abab2
Reduce docs workflow to build-only check
lipkau May 19, 2026
41e3bec
Remove duplicate docs build workflow
lipkau May 19, 2026
a49263b
Revert JiraAgilePS route workaround
lipkau May 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 34 additions & 111 deletions docs/Contributing/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
| ----------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
Expand All @@ -87,56 +37,37 @@ Each of our projects has an _Issuetracker_ where you can report your findings.
| **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/HipchatPSPS.svg?maxAge=2592000)](https://github.com/AtlassianPS/HipchatPS/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) |

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.

Expand All @@ -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 <https://github.com/codespaces>
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.

<!-- reference-style links -->
[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
142 changes: 33 additions & 109 deletions docs/Contributing/our-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<command name>` (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.

<!-- reference-style links -->
[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
Loading
Loading