Skip to content

docs(governance): add governance model, PR checks, and contribution templates #2307

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
bruno-andrade-azion merged 1 commit into from
Aug 10, 2026
Merged

docs(governance): add governance model, PR checks, and contribution templates #2307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
16 changes: 11 additions & 5 deletions .github/CODEOWNERS
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
* @isaquebock @egermano @souzavinny @pedroribeiroazion
# Default: DevRel owns the project
* @isaque-bock-azion @bruno-andrade-azion @marcus-souza-azion @pedro-ribeiro-azion

src/content/docs @aziontech/product-content
src/i18n @aziontech/product-content
RADME.md @aziontech/experience-engineering @aziontech/product-content
LICENSE @aziontech/experience-engineering @aziontech/product-content
# Platform/structure code → DevRel + UX Engineering (technical steward)
src/ @aziontech/team-uxe
/astro.config.* @aziontech/team-uxe
/package*.json @aziontech/team-uxe
.github/workflows/ @aziontech/team-uxe

# Published content + i18n
src/content/docs/ @aziontech/product-content
src/i18n/ @aziontech/product-content
150 changes: 40 additions & 110 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,130 +1,60 @@
# Azion Docs contributing guide
# Contributing to Azion Docs

Thank you for taking the time to contribute to the Azion documentation! :orange_heart:
Thanks for helping improve [Azion Developer Documentation](https://azion.com/en/documentation/)!

Your contributions will help us maintain the [Azion Docs](https://docs.azion.com) portal.
## The 60-second version:
1. Open an issue (or grab one) → 2. Branch from `main` → 3. Write the page → 4. Run `pnpm build:local` → 5. Open a PR with a [conventional title](GOVERNANCE.md#4-pr-standard-enforced-by-ci) → 6. CI + two reviewers → 7. Squash-merge

In this guide you'll get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.
Rules of the road live in [GOVERNANCE.md](GOVERNANCE.md). This page is the practical walkthrough.

> :wave: **New to contributions?** To get an overview of the project, read the [README](README.md) file. Here are some resources to help you get started with open source contributions:
> - [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github)
> - [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git)
> - [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow)
> - [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests)
## Before you write

- Search existing issues first. If none fits, open one via the [issue forms](https://github.com/aziontech/docs/issues/new/choose) (Add / Upkeep / Fix / Question).
- Small fixes (typos, broken links) can skip the issue and go straight to a PR.
- Who reviews what is defined only in [`.github/CODEOWNERS`](CODEOWNERS). If you read a list of names anywhere else, trust CODEOWNERS.

## Important
## Setup

- In the Azion **docs** repository, you can open an issue without opening a PR after, but you should open an issue before opening a PR.
- PRs with only minor changes can be opened without an issue.
- PRs submitted by code owners (internal) have priority over PRs submitted by external users (external).
- For significant changes on docs, we recommend you open an issue and wait for one of our code owners to respond so we can find the best approach.
```bash
git clone https://github.com/aziontech/docs.git # or your fork (external contributors)
cd docs
nvm use # Node version from .nvmrc
pnpm install --frozen-lockfile # pnpm is the package manager of record. Do not commit npm/yarn lockfiles
pnpm dev # local preview
```

## Code owners
## Making changes

`aziontech/docs` has two teams as code owners:
- All content lives in `src/content/docs/{en,pt-br}` as `.mdx`. English is the source of truth, so write it first. Add the `pt-br` version in the same PR when you can.
- Trunk-based flow: `main` is the only long-lived branch. Branch off it (`EDU-1234-short-slug` or `type/short-slug`), keep the branch alive **3 days or less**, and PR back into `main`. Do not push to `main` directly, do not commit through the web UI, and do not keep personal long-running branches. Embargoed launch content merges behind a draft/publish frontmatter gate instead of waiting in a branch.
- One concern per PR. Content changes and platform/code changes never travel together.

- Developer education, the gatekeepers of all content.
-
- [@guiafonso-ol](https://github.com/guiafonso-ol) :dog:
- [@GabrielAzion](https://github.com/GabrielAzion) :owl:
- [@LuizaVSantos](https://github.com/LuizaVSantos) :guitar:
- [@MarianaReisAlcantara](https://github.com/MarianaReisAlcantara) :panda_face:
## Before opening the PR

- UX Engineering (UXE), the gatekeepers of all structure code.
```bash
pnpm build:local # build + frontmatter validation (CI runs this too)
pnpm lint:slugcheck # permalink rules
```

- [@robsongajunior](https://github.com/robsongajunior)
- [@lfsigreja](https://github.com/lfsigreja )
- Changed a permalink or moved a page? **Add the redirect in this PR.**
- Can't update `pt-br` yourself? Create the follow-up `i18n` issue and link it in the PR checklist.

---
## The PR

## Getting started
- Title: `type(scope): imperative summary`, enforced by CI. **No ticket codes in the title**: the branch name and the Related issue field carry those, and squash makes titles permanent history.
- `feat` new content · `fix` corrections · `docs` upkeep · `i18n` translation · `refactor`/`chore` structure & tooling
- Fill the PR template. The checklists are the review contract, and reviewers will hold you to them.
- Two people sign off: an SME confirms it's technically true, and a DevRel maintainer confirms it's well written and well placed. Expect a first response within 1 business day. Short-lived branches only work when reviews are fast.
- Merges are **squash-only**; your PR title becomes the permanent commit message.

### :grey_exclamation: Open a new issue
## External contributors

If you spot a problem with the docs, first [search if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments) in the Azion Docs repository.
Fork → branch → PR to `main`. Enable "allow maintainer edits" so we can help you across the finish line. Internal team PRs may take priority when a launch is in flight, but community PRs get folded in and credited.

If a related issue doesn't exist, you can open a new issue using one of the [issue forms](https://github.com/aziontech/docs/issues/new/choose).
## AI-assisted contributions

There are 4 types of contribution to the Azion Docs repository:
Welcome, and held to identical standards. Whether the branch came from you, Codex, Copilot, or Claude, it meets the same template, title, and checklist requirements as any other PR. You are accountable for the accuracy of what the agent wrote, and "the AI generated it" is not a review response.

- **Add**: addition of new content.
- **Upkeep**: update of existing content.
- **Fix**: correction of content errors.
- **Questions**: doubts.
## After the merge

### :pencil2: Make changes

After you open an issue, you can either start making changes yourself or wait for one of our tech writers to address your issue.

Only code owners from the [Azion organization](https://github.com/aziontech/) can directly create branches and open pull requests on the docs repository. If you aren't part of the Azion organization but want to contribute, [fork the repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) first.

In your fork, make the necessary modifications to the files. The directory path `src/content/docs` holds all of the content in the Azion Docs portal, divided by language.

If you feel confident writing in both English and Portuguese, don't forget to make the changes to both English and Portuguese versions of the documentation. Otherwise, one of our team members will open a PR for the other language on your behalf.

Azion Docs uses the [Astro framework](https://docs.astro.build/en/guides/markdown-content/), allowing you to write content in `.mdx` format. Take a look at [some of our existing content](https://github.com/aziontech/docs/tree/community-guidelines/src/content/docs) to get a sense of how our documentation is structured.

If you want to propose a new page:

1. Find the appropriate directory.
2. Create a new `.mdx` file.
3. Add a [front matter YAML](https://docs.github.com/en/github-ae@latest/contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter) to the top of the `.mdx` file to fill out titles and metadata as shown below:

```md
---
title: <Insert page title>
description: <Insert page description>
meta_tags: <Insert tags>
namespace: <Insert namespace following the structure: documentation_type_product_module_feature>
permalink: <Insert a permalink for the page following the structure: /en/documentation/type/product/module/feature>
---
```

4. Write the content below the front matter in Markdown format.

You can branch out from main or commit the changes directly once you're pleased with them. We use the basics of the **Conventional Commits** standard to title commits and PRs.

### :speech_balloon: Create a Pull Request

When you're finished with the changes, create a pull request (PR).

1. [Open a new PR](https://github.com/aziontech/docs/compare) by selecting your forked repository and the branch in which you commited your changes.
2. Fill in the PR title and description according to the template so that we can review your PR.
- The description template helps reviewers understand your changes as well as the purpose of your PR.
3. Don't forget to [link the PR to the issue you opened](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
4. Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so the branch can be updated for a merge.
5. Once you submit your PR, our code owners will review your contributions. We may ask questions or request additional context.
- Reviewers will test your changes locally to make sure your modifications don't break the application's build process.
6. After testing, we may ask for changes to be made before a PR can be merged, either using [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) or pull request comments.
- You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
7. As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).

Now you'll need the approval from at least two code owners before you can merge your changes.

#### :memo: Review by code owners

When the repository's code owners review your PR, they may make suggestions, request changes, or even reject your PR. Possibilities that lead to a PR rejection:

- PR based on the wrong branch (not main).
- PR attempts to merge changes into the wrong branch.
- Contribution was already addressed in another PR.
- Contribution has wrong technical information. Address the responsible Technical Writer (TW) and a Subject Matter Expert (SME), if needed.
- Contribution is already being worked on by a TW (if it’s a product/feature launch and the TW is already working on the content on a branch, the TW’s contribution has priority. Community contribution can be incorporated into the TW’s PR).
- Contributor opened a PR with major changes without a GitHub issue.
- Contributor didn’t describe what they were changing/adding/fixing on the PR description.
- Contributor didn’t add a descriptive title/label.

### :thumbsup: Merge changes

Once you have at least two approvals from code owners, you can merge your PR! 🥳

Check the [GitHub Actions tab](https://github.com/aziontech/docs/actions) to see the status of your modifications. If you run into any merge issues, check this [git tutorial](https://github.com/skills/resolve-merge-conflicts) to help you resolve merge conflicts and other issues.

Once your PR is merged successfully, you can review your contribution on the [Azion Docs](https://docs.azion.com) portal. 📙

### :white_check_mark: Close the issue

Congratulations, your PR has been merged! :tada: The issue you created can now be updated and closed once the merge has been made.

> Don't forget to [keep your forked repository up-to-date with the Azion docs repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) if you wish to make more contributions in the future.
CI deploys `main` to production automatically. Check your page on [https://azion.com/en/documentation/](https://azion.com/en/documentation/), then close the issue.
98 changes: 98 additions & 0 deletions .github/GOVERNANCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# Azion Docs Governance

How contributions move through `aziontech/docs`: who owns what, what needs whose approval, and the conventions everyone follows. If another document in this repo contradicts this one, this one wins and the other gets a PR.

- How to contribute → [CONTRIBUTING.md](CONTRIBUTING.md)
- Who reviews what → [CODEOWNERS](CODEOWNERS)

## Principles

1. **Docs are an API.** People read these pages, and so do agents and crawlers through llms.txt, context7, and MCP. Frontmatter, heading structure, and working links are part of the contract.
2. **English is the source of truth.** `pt-br` mirrors `en`. When they drift, that gets tracked in an `i18n` issue rather than left silent.
3. **URLs are forever.** Moving or renaming a page means adding a redirect in the same PR.
4. **One PR, one concern.** Content and platform code don't travel together.

## Roles

| Role | Who | Owns |
|---|---|---|
| DevRel | The default owners in [CODEOWNERS](CODEOWNERS) | The project: content, style, IA, i18n, roadmap. Default owner and the final say on everything |
| DevRel lead | The project owner named under Escalation | The calls that are hard to undo: deleting pages, IA changes, changes to this document |
| UX Engineering | `@aziontech/team-uxe` | Platform code: `src/` components, config, CI. Co-reviews with DevRel |
| Product content | `@aziontech/product-content` | Published content and translations |
| SMEs | The relevant product team | Technical accuracy in their area |
| Contributors | Anyone, internal or external | Proposing changes through an issue and a PR |

Technical content passes two gates: an SME confirms it's true, and DevRel confirms it's well written and well placed. Neither substitutes for the other. CODEOWNERS requests one reviewer set per path, so not every approval in the table below is routed automatically. The author requests whoever CODEOWNERS didn't, starting with the SME, since there are no per-product entries.

## What needs what

| Change | Issue first? | Approvals |
|---|---|---|
| Typo, broken link, formatting | No | 1 DevRel |
| Update an existing page | Recommended | 1 DevRel, plus an SME if technical claims change |
| New page | Yes | 1 SME + 1 DevRel |
| Delete or move a page, change a permalink | Yes | 1 DevRel + DevRel lead, and the redirect ships in the same PR |
| Nav, menu, or IA change | Yes | DevRel lead + 1 UXE |
| Platform code (`src/`, config, CI) | Yes | 1 UXE + 1 DevRel |
| Change to this document | Yes, as a proposal | DevRel lead, with a comment window for affected teams |

## How a change moves

Open an issue, or pick up an existing one. Small fixes can skip straight to a PR.

Branch off `main`, which is the only branch anyone works from. Name it `EDU-1234-short-slug` or `type/short-slug`. Keep it short-lived: days, not weeks. Long branches are where merge pain and stale content come from, so if a branch is growing past a week, split it or land what's ready.

Don't park unfinished work in a branch waiting for a launch date. Either keep the PR small enough to merge on the day, or merge it behind a frontmatter flag that keeps the page out of nav, sitemap, and search until it's ready.

Open the PR against `main` and fill in the template. Merges are squash-only, so the PR title becomes the permanent commit message.

After merge, CI builds and deploys `main` to production.

## PR conventions

Titles follow `type(scope): imperative summary`, checked by CI.

- Types: `feat` (new content), `fix` (corrections), `docs` (upkeep and rewrites), `i18n` (translation sync), `refactor` (structure, no meaning change), `chore` (deps and tooling)
- Scope: a journey or product slug, like `secure`, `build`, `functions`, `object-storage`
- Good: `docs(secure): clarify Bot Manager scoring rules`
- Not this: `fix typo` · `Update en.json` · `Enhance documentation on...`

No ticket codes in the title. Squash merge makes titles permanent history and `[EDU-1234]` adds nothing there. The ticket lives in the branch name, which Jira links automatically, and in the PR body.

Keep PRs to roughly 400 changed lines of prose, translations excluded. Bigger ones are harder to review well, so split them unless there's a reason not to.

AI-assisted PRs follow the same rules as any other. The author, not the agent, is accountable for accuracy.

## What CI checks

On every PR: the site builds, frontmatter namespaces and permalinks are present and unique, and the PR title matches the convention. A broken build or a duplicate permalink blocks the merge.

Weekly: a link check crawls the built site for broken internal links and opens an issue when it finds them.

Everything else in this document is a convention that reviewers uphold, which is how most of it will always work.

## Review expectations

| Situation | Target |
|---|---|
| First response on any PR | 1 business day |
| Typos and broken links | Same day |
| Full review | 3 business days |

These are targets, not guarantees, but they matter more than usual here: short-lived branches only work if reviews are quick. If they slip consistently, the answer is more reviewer capacity, not longer branches.

A PR that goes quiet on the contributor's side gets a nudge, and may be closed after a couple of weeks with an invitation to reopen. A PR waiting on us is never closed for age.

## Maintenance and deprecation

Pages go stale. DevRel reviews the oldest content periodically and files upkeep issues for what needs attention.

When a feature is deprecated, its page gets a banner and a pointer to the replacement for one release cycle, then a redirect. The content stays in git history rather than ranking in search.

## Escalation

If an SME and DevRel disagree, @bruno-andrade-azion decides and the decision is recorded in the PR. To propose a change to this document, open an issue with the `governance` label.

---
*Owner: DevRel*
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/content.fix.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ body:
- type: textarea
attributes:
label: Documentation URLs
description: Please, provide links to the existing [Azion Docs](https://docs.azion.com) page or pages that contain the error.
description: Please, provide links to the existing [Azion Docs](https://azion.com/en/documentation/) page or pages that contain the error.
validations:
required: true

Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/content.upkeep.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ body:
- type: textarea
attributes:
label: Documentation URLs
description: Please provide links to one of our existing [Azion Docs](https://docs.azion.com) pages.
description: Please provide links to one of our existing [Azion Docs](https://azion.com/en/documentation/) pages.
validations:
required: true

Expand Down
Loading
Loading