diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 995e3d4c74..7a481f923e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -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 \ No newline at end of file diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ce3ac5b5d7..7ede43cbd2 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -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: - description: - meta_tags: - namespace: - permalink: - --- - ``` - -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. diff --git a/.github/GOVERNANCE.md b/.github/GOVERNANCE.md new file mode 100644 index 0000000000..d4c228224b --- /dev/null +++ b/.github/GOVERNANCE.md @@ -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* diff --git a/.github/ISSUE_TEMPLATE/content.fix.yml b/.github/ISSUE_TEMPLATE/content.fix.yml index 2247150bd2..12d5253eef 100644 --- a/.github/ISSUE_TEMPLATE/content.fix.yml +++ b/.github/ISSUE_TEMPLATE/content.fix.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/content.upkeep.yml b/.github/ISSUE_TEMPLATE/content.upkeep.yml index 80e555246f..671bc1930a 100644 --- a/.github/ISSUE_TEMPLATE/content.upkeep.yml +++ b/.github/ISSUE_TEMPLATE/content.upkeep.yml @@ -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 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 3f9dd9c560..98089d458e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,23 +1,24 @@ - +**Related issue:** +**Pages affected:** -### Related issue: +## Type of change -### Changes +- [ ] 🆕 New content (`feat`) +- [ ] 🩹 Fix (`fix`) — typo, broken link, wrong information +- [ ] ♻️ Content update (`docs`) — rewrite, expansion, upkeep +- [ ] 🌐 Translation sync (`i18n`) +- [ ] 🏗️ Platform / structure (`refactor` / `chore`) — reviewed by UXE, no content mixed in - +## Author checklist -### Additional links - - +- [ ] PR title follows `type(scope): summary` (see [GOVERNANCE.md §4](GOVERNANCE.md)) +- [ ] Frontmatter complete: `title`, `description`, `meta_tags`, `namespace`, `permalink`, `last_reviewed` +- [ ] No legacy "edge-" product names in the copy +- [ ] How-to/tutorial content includes at least one runnable, copy-paste-tested code block +- [ ] Screenshots (if any) have alt text and follow image standards +- [ ] Internal links are relative and resolve locally +- [ ] **If any permalink changed or page moved: redirect added in this PR** +- [ ] **i18n:** `pt-br` updated in this PR **or** follow-up `i18n` issue created: +- [ ] I ran `pnpm build:local` (build + frontmatter check) without errors \ No newline at end of file diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml new file mode 100644 index 0000000000..353cc10815 --- /dev/null +++ b/.github/workflows/pr-checks.yml @@ -0,0 +1,38 @@ +name: PR checks +on: + pull_request: + branches: + - main + types: [opened, synchronize, reopened] + +concurrency: + group: pr-checks-${{ github.event.pull_request.number }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + validate: + name: Build and frontmatter + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up pnpm + uses: pnpm/action-setup@v4 + + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: 22.23.2 + cache: pnpm + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Build and validate frontmatter + run: pnpm build:local + env: + NODE_OPTIONS: --max-old-space-size=8120 diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml new file mode 100644 index 0000000000..d7edc74737 --- /dev/null +++ b/.github/workflows/pr-title.yml @@ -0,0 +1,46 @@ +name: PR title +on: + pull_request: + types: [opened, edited, reopened, synchronize] + +concurrency: + group: pr-title-${{ github.event.pull_request.number }} + cancel-in-progress: true + +permissions: + pull-requests: read + +jobs: + title: + name: Conventional title, no ticket codes + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - name: Check type(scope) format + uses: amannn/action-semantic-pull-request@v5 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + types: | + feat + fix + docs + i18n + refactor + chore + requireScope: true + # Imperative summaries start lowercase. This is what rejects + # "Enhance documentation on..." and "Update en.json". + subjectPattern: ^(?![A-Z]).+$ + subjectPatternError: > + The summary "{subject}" must start with a lowercase letter and read as an + imperative, for example "clarify Bot Manager scoring rules". + + - name: Reject ticket codes in the title + env: + PR_TITLE: ${{ github.event.pull_request.title }} + run: | + if printf '%s' "$PR_TITLE" | grep -qE '^\[?[A-Z]{2,}-[0-9]+\]?|\[[A-Z]{2,}-[0-9]+\]'; then + echo "::error::Ticket codes do not belong in PR titles. Put the ticket in the branch name (EDU-1234-short-slug) and the Related issue field in the PR body." + exit 1 + fi diff --git a/.github/workflows/weekly-linkcheck.yml b/.github/workflows/weekly-linkcheck.yml new file mode 100644 index 0000000000..1b432b4a3f --- /dev/null +++ b/.github/workflows/weekly-linkcheck.yml @@ -0,0 +1,78 @@ +name: Weekly link check +on: + schedule: + - cron: '0 6 * * 1' # Mondays 06:00 UTC, 03:00 GMT-3 + workflow_dispatch: + +permissions: + contents: read + issues: write + +jobs: + linkcheck: + name: Internal links + runs-on: ubuntu-latest + timeout-minutes: 45 + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up pnpm + uses: pnpm/action-setup@v4 + with: + version: 10 + + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: 20.13.1 + cache: pnpm + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Check internal links + id: linkcheck + run: | + pnpm build:local + pnpm exec tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/lint-linkcheck.ts + env: + SKIP_OG: 'true' + NODE_OPTIONS: --max-old-space-size=8120 + + - name: File an issue on breakage + if: steps.linkcheck.conclusion == 'failure' + uses: actions/github-script@v7 + with: + script: | + const label = 'broken-links'; + const existing = await github.rest.issues.listForRepo({ + owner: context.repo.owner, + repo: context.repo.repo, + state: 'open', + labels: label, + }); + const run = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; + const open = existing.data.filter((i) => !i.pull_request); + if (open.length > 0) { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: open[0].number, + body: `Still failing as of the latest run: ${run}`, + }); + return; + } + await github.rest.issues.create({ + owner: context.repo.owner, + repo: context.repo.repo, + title: 'Weekly link check is failing', + labels: [label], + body: [ + 'The weekly internal link check failed.', + '', + `Run: ${run}`, + '', + 'This issue stays open and collects a comment per failing run. Close it once the run is green.', + ].join('\n'), + }); diff --git a/README.md b/README.md index f0c68ef931..957c4215af 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,79 @@ +

Azion Docs

-

- Azion Docs 💻📚🧡 -

- -![docs production](https://github.com/aziontech/docs/actions/workflows/prod.yml/badge.svg) -![docs stage](https://github.com/aziontech/docs/actions/workflows/stage.yml/badge.svg) -![docs development](https://github.com/aziontech/docs/actions/workflows/dev.yml/badge.svg) +

+ The source for Azion's developer documentation. +
+ Built with Astro and MDX, in English and Portuguese. +

- We're under a MIT license. -
- You can read more about it on LICENSE. + production build + MIT license

-- [About us](#about-us-%E2%84%B9%EF%B8%8F) -- [Contributions](#contributions-) -- [Community](#community-) +--- + +## Quick links + +| If you want to | Go to | +| --- | --- | +| Read the documentation | [azion.com/en/documentation](https://azion.com/en/documentation/) | +| Report an error, request a page, or ask a question | [Issue forms](https://github.com/aziontech/docs/issues/new/choose) | +| Make a change | [CONTRIBUTING.md](.github/CONTRIBUTING.md) | +| Understand the rules | [GOVERNANCE.md](.github/GOVERNANCE.md) | +| Find out who reviews what | [CODEOWNERS](.github/CODEOWNERS) | +| Get help with an Azion product | [Azion Support](https://tickets.azion.com/en/support/login/new) | -Welcome to our open documentation repository! We're thrilled that you're interested in contributing to our documentation and being a part of our community. This README will go over the mission to empower Azion users through effective and clear documentation, as well as introduce how anyone willing to do good can help us by contributing. 📖 +## What's in here -## About Us ℹ️ +Published content lives in `src/content/docs/`, split into `en` and `pt-br`. Pages are `.mdx`, so a page can pull in front-end components instead of being limited to prose. The site covers product reference, API reference, guides, use cases, and code samples. -We are a web platform that allows you to build and run applications anywhere. Our documentation is a crucial part of ensuring our users have the best experience with our products and services. 🌐🚀 +English is the source of truth. Portuguese mirrors it, and divergence is tracked in an `i18n` issue rather than left silent. -Our documentation includes: +We treat these pages as an API. People read them, but so do agents and crawlers through llms.txt, context7, and MCP. That makes frontmatter schema, heading structure, and working links contract requirements rather than style preferences. -- Product reference -- API reference -- Guides -- Use cases -- Code samples +## Run it locally -The documentation portal is built on [Astro](https://docs.astro.build/en/getting-started/) and leverages [MDX](https://mdxjs.com/docs/what-is-mdx/) to build experience-focused content with front-end components, going beyond text. +You need Node 20.13.1 or newer and pnpm. -## Contributions 🤝 +```bash +git clone https://github.com/aziontech/docs.git +cd docs +nvm use +pnpm install --frozen-lockfile +pnpm dev +``` -We encourage and welcome contributions from the community. Whether you've found a typo, want to fix a bug, or add new content, your help is greatly appreciated. To get started, please [go to Azion Docs Contributing guide](https://github.com/aziontech/docs/blob/main/.github/CONTRIBUTING.md) to get familiar with the process. +Before you open a pull request: -### Contributor Covenant Code of Conduct 📜 +```bash +pnpm build:local # build + frontmatter validation +pnpm lint:slugcheck # permalink rules +``` -To maintain the quality and integrity of our documentation, contributors are required to read our [Contributor Covenant Code of Conduct](https://github.com/aziontech/docs/blob/main/CODE_OF_CONDUCT.md). 📝🤝 +pnpm is the package manager of record. Do not commit npm or yarn lockfiles. -## Community 💬 +## How changes get made -You can find us on: +[GOVERNANCE.md](.github/GOVERNANCE.md) is the source of truth. If it contradicts any other document in this repository, including this one, it wins. The short version: + +- `main` is the only long-lived branch. Work happens on short-lived branches that merge back within days. +- Merges are squash only, so the pull request title becomes permanent commit history. Titles follow `type(scope): summary` and never carry ticket codes. +- Technical content passes two gates. A subject matter expert confirms it is true, and a DevRel maintainer confirms it is well written and well placed. +- A permalink change without a redirect in the same pull request is a broken build. +- Expect a first response on any pull request within one business day. + +[CONTRIBUTING.md](.github/CONTRIBUTING.md) walks through all of it step by step. Contributions from outside Azion are welcome and get credited: fork the repository, branch, and open a pull request against `main`. + +## Community - [Discord](https://discord.com/invite/Yp9N7RMVZy) -- [X](https://x.com/aziontech) +- [X](https://x.com/aziontech) - [LinkedIn](https://www.linkedin.com/company/aziontech) - [YouTube](https://www.youtube.com/aziontech) -Thank you for considering contributing to our documentation. Together, we can empower our community with valuable resources. 🧡🙏 +Everyone taking part here follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). + +## License + +Released under the [MIT License](LICENSE). Copyright (c) 2026 Azion Technologies.