Thank you for taking the time to contribute to the Azion documentation! 🧡
Your contributions will help us maintain the Azion Docs portal.
In this guide you'll get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.
👋 New to contributions? To get an overview of the project, read the README file. Here are some resources to help you get started with open source contributions:
- 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.
aziontech/docs has two teams as code owners:
-
Product Content Experience (PCX), the gatekeepers of all content.
-
UX Engineering (UXE), the gatekeepers of all structure code.
If you spot a problem with the docs, first search if an issue already exists in the Azion Docs repository.
If a related issue doesn't exist, you can open a new issue using one of the issue forms.
There are 4 types of contribution to the Azion Docs repository:
- Add: addition of new content.
- Upkeep: update of existing content.
- Fix: correction of content errors.
- Questions: doubts.
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 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 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, allowing you to write content in .mdx format. Take a look at some of our existing content to get a sense of how our documentation is structured.
If you want to propose a new page:
- Find the appropriate directory.
- Create a new
.mdxfile. - Add a front matter YAML to the top of the
.mdxfile to fill out titles and metadata as shown below:
---
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>
---- 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.
When you're finished with the changes, create a pull request (PR).
- Open a new PR by selecting your forked repository and the branch in which you commited your changes.
- 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.
- Don't forget to link the PR to the issue you opened.
- Enable the checkbox to allow maintainer edits so the branch can be updated for a merge.
- 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.
- After testing, we may ask for changes to be made before a PR can be merged, either using suggested changes 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.
- As you update your PR and apply changes, mark each conversation as resolved.
Now you'll need the approval from at least two code owners before you can merge your changes.
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.
Once you have at least two approvals from code owners, you can merge your PR! 🥳
Check the GitHub Actions tab to see the status of your modifications. If you run into any merge issues, check this git tutorial to help you resolve merge conflicts and other issues.
Once your PR is merged successfully, you can review your contribution on the Azion Docs portal. 📙
Congratulations, your PR has been merged! 🎉 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 if you wish to make more contributions in the future.