From a8a40ffccbbf01883e0fb72b5d75d4bf47f068be Mon Sep 17 00:00:00 2001 From: Juminstock Date: Thu, 4 Jun 2026 13:03:40 -0500 Subject: [PATCH 1/2] docs: add contribution standards and partner integration guide Adds CONTRIBUTING.md with eligibility criteria, two-stage proposal process, documentation standards, and review SLA. Adds GitHub issue templates for integration requests and content updates, a PR template checklist, and a Partner and Tooling Contributions section in README. --- .../ISSUE_TEMPLATE/content-update-request.yml | 42 +++++ .../new-integration-request.yml | 104 ++++++++++++ .github/pull_request_template.md | 30 ++++ CONTRIBUTING.md | 153 ++++++++++++++++++ README.md | 46 ++++++ 5 files changed, 375 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/content-update-request.yml create mode 100644 .github/ISSUE_TEMPLATE/new-integration-request.yml create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/content-update-request.yml b/.github/ISSUE_TEMPLATE/content-update-request.yml new file mode 100644 index 00000000000..99ae2ee7890 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/content-update-request.yml @@ -0,0 +1,42 @@ +name: Content Update Request +description: Report incorrect, outdated, or incomplete content in the Astar documentation +title: "[Content Update] " +labels: ["content update"] +body: + - type: markdown + attributes: + value: | + Use this template to flag content that is wrong, outdated, or missing important information. + For small fixes like typos or broken links, you may open a pull request directly without an issue. + + - type: input + id: page-url + attributes: + label: Page URL or File Path + description: Link to the documentation page or the file path in the repository + placeholder: https://docs.astar.network/docs/... or docs/path/to/file.md + validations: + required: true + + - type: textarea + id: current-content + attributes: + label: Current Content + description: Copy the text or describe the section that needs updating + validations: + required: true + + - type: textarea + id: proposed-change + attributes: + label: Proposed Change + description: Describe what the correct or updated information should be + validations: + required: true + + - type: input + id: source + attributes: + label: Source or Reference + description: Link to an official source confirming the correct information (strongly recommended) + placeholder: https://official-docs-or-announcement-link diff --git a/.github/ISSUE_TEMPLATE/new-integration-request.yml b/.github/ISSUE_TEMPLATE/new-integration-request.yml new file mode 100644 index 00000000000..8ff5e1ef69a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new-integration-request.yml @@ -0,0 +1,104 @@ +name: New Integration or Tooling Request +description: Request the inclusion of a new project, tool, or integration in the Astar documentation +title: "[Integration Request] " +labels: ["integration request", "documentation"] +body: + - type: markdown + attributes: + value: | + Thank you for your interest in being documented in the Astar docs. + Please complete all fields accurately. Incomplete requests or projects that do not meet the eligibility criteria will be closed without review. + Before submitting, confirm your project is live on **Astar EVM mainnet**. + + - type: input + id: project-name + attributes: + label: Project Name + description: The official name of your project or tool + placeholder: e.g. CometSwap + validations: + required: true + + - type: dropdown + id: category + attributes: + label: Category + description: Select the category that best describes your project + options: + - Bridge + - DEX / AMM + - Lending / Borrowing + - Wallet + - Oracle + - NFT Marketplace + - Infrastructure / RPC + - Developer Tooling + - Analytics + - Other + validations: + required: true + + - type: input + id: deployment-url + attributes: + label: Live Deployment URL + description: The URL of your live, Astar EVM mainnet-deployed application + placeholder: https://yourproject.app + validations: + required: true + + - type: input + id: official-website + attributes: + label: Official Website + placeholder: https://yourproject.com + validations: + required: true + + - type: input + id: github-repo + attributes: + label: GitHub Repository (if open source) + placeholder: https://github.com/yourorg/yourrepo + + - type: input + id: docs-section + attributes: + label: Proposed Documentation Section + description: Which section of the docs should your project appear in? + placeholder: e.g. docs/use/integrations or docs/build/tooling + validations: + required: true + + - type: textarea + id: description + attributes: + label: Project Description + description: A concise, factual description of what your project does and how it relates to the Astar ecosystem. Maximum 300 words. No marketing language. + validations: + required: true + + - type: textarea + id: why-include + attributes: + label: Why should this be included? + description: Explain the value this documentation provides to Astar EVM developers or users + validations: + required: true + + - type: checkboxes + id: checklist + attributes: + label: Eligibility Checklist + description: All items must be confirmed before your request will be reviewed + options: + - label: My project is live on Astar EVM mainnet (not testnet only) + required: true + - label: My project is actively maintained + required: true + - label: This documentation does not already exist in these docs + required: true + - label: I am authorized to represent this project + required: true + - label: I have read the CONTRIBUTING.md guidelines + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000000..1bbb881fe6b --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,30 @@ +## Description + + + +## Type of Change + +- [ ] Bug fix (typo, broken link, outdated information) +- [ ] New integration or tooling documentation +- [ ] New tutorial or guide +- [ ] Structural or navigation improvement +- [ ] Other + +## Linked Issue + +Closes # + +## Checklist + +- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines +- [ ] The build passes locally (`yarn build`) +- [ ] All links in changed files are working +- [ ] Images use the `
` component with absolute paths +- [ ] Content is factual and contains no marketing language +- [ ] The file structure follows the existing documentation hierarchy + +## For New Integration PRs Only + +- [ ] The project is live on Astar EVM mainnet +- [ ] An approved integration request issue exists (Issue #___) +- [ ] Page structure follows the existing format for this category diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..bc35c4230f4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,153 @@ +# Contributing to Astar Documentation + +Thank you for your interest in contributing to the Astar documentation. This guide explains who can contribute, what standards apply, and the process for getting new integrations or tooling listed. + +## Types of Contributions + +| Type | Description | +| --- | --- | +| **Bug fix** | Correcting typos, broken links, or factually incorrect information | +| **Content update** | Updating outdated instructions, screenshots, or network parameters | +| **New tutorial** | Adding a step-by-step guide for using a feature or tool in the Astar ecosystem | +| **New integration** | Requesting that a partner project, protocol, or developer tool be documented | +| **Structural improvement** | Reorganizing content for clarity without changing the underlying information | + +All contributions go through a pull request and require at least one approval from the Astar documentation team before merging. + +## Partner and Tooling Inclusion + +This section is specifically for teams or individuals who want to get a project, protocol, or tool documented in the Astar docs. + +### Eligibility Criteria + +Before opening a request, your project must meet all of the following: + +- **Live on mainnet.** Your project must be deployed and functional on Astar EVM. Testnet-only projects are not accepted. +- **Actively maintained.** The project must show recent activity. Abandoned or deprecated projects will not be added and existing ones may be removed. +- **Not a duplicate.** The documentation you are proposing must not already exist or substantially overlap with existing content. +- **Factual and technical.** The documentation must describe how to use or integrate the product. Marketing copy, price information, and investment language are not accepted. +- **Authorized submission.** You must be an official representative of the project or have explicit permission to submit documentation on its behalf. + +### The Two-Stage Process + +New integration documentation follows a proposal-first workflow. A PR submitted without an approved issue will be closed. + +#### Stage 1: Open an Integration Request Issue + +Use the [New Integration Request](.github/ISSUE_TEMPLATE/new-integration-request.yml) issue template. You will be asked to provide: + +- Project name and category +- Live deployment URL on Astar EVM +- Official website and GitHub repository (if open source) +- The section of the docs where your content belongs +- A factual description of what the project does + +The documentation team will review the request within **5 business days** and respond with one of the following: + +- **Approved**: You are invited to open a PR with the documentation +- **Needs more information**: The team will request clarification before making a decision +- **Declined**: The request does not meet the eligibility criteria; a reason will be provided + +#### Stage 2: Open a Pull Request + +Once your issue is approved, open a PR that: + +- References the approved issue number in the description +- Follows the file structure and style guide described below +- Passes the automated CI build (`yarn build`) +- Uses the PR template checklist + +### What Happens After Your PR Is Submitted + +1. **Automated checks** run first: the build must pass and links must resolve +2. **Content review** by the documentation team checks accuracy, tone, and structure +3. **One approval** is required from a team member before merge +4. Once merged, the content appears on [docs.astar.network](https://docs.astar.network) within minutes + +## Documentation Standards + +### File Structure + +Place new documentation files in the correct section of the `docs/` directory. Follow the existing hierarchy: + +``` +docs/ + build/ Developer tools, integrations, EVM/WASM guides + use/ End-user guides: wallets, bridges, dApp staking + learn/ Conceptual content: architecture, tokenomics +``` + +If you are unsure where your content belongs, ask in the linked issue before creating files. + +### Page Structure + +Every new page should include: + +1. **Frontmatter** with at minimum `sidebar_position` and a `title` +2. **Overview paragraph** explaining what the page covers and who it is for +3. **Prerequisites** (if applicable) listing what the reader needs before starting +4. **Step-by-step content** using numbered lists for sequential actions +5. **Troubleshooting or notes** (if applicable) using Docusaurus admonition blocks (`:::info`, `:::caution`, `:::warning`) + +### Writing Style + +- Write in the **second person** ("you", "your") and **present tense** +- Use **active voice**: "Click the button" not "The button should be clicked" +- Keep sentences short. One idea per sentence +- Spell out acronyms on first use: "Decentralized Exchange (DEX)" +- Do not include prices, APY, TVL, or other figures that change over time +- Do not include referral links or promotional language + +### Images + +Always use the `
` component instead of standard markdown image syntax. This ensures proper rendering across all locales. + +**Import at the top of the file:** +```jsx +import Figure from '/src/components/figure' +``` + +**Usage:** +```jsx +
+``` + +Use **absolute paths** for images. Relative paths will break when content is reorganized. + +### Code Blocks + +Always specify the language for syntax highlighting: + +````markdown +```typescript +const example = "always add the language" +``` +```` + +## Updating Existing Documentation + +To report or correct outdated, incorrect, or incomplete content, open a [Content Update Request](.github/ISSUE_TEMPLATE/content-update-request.yml) issue. Include: + +- The URL or file path of the page in question +- The current content that needs changing +- The proposed correction and a source or reference confirming it + +For small corrections (typos, broken links), you may open a PR directly without an issue. + +## Review SLA + +| Action | Expected Response Time | +| --- | --- | +| New integration request issue review | 5 business days | +| Content update issue review | 3 business days | +| PR review after CI passes | 3 business days | + +If you have not received a response within these timeframes, feel free to leave a comment on your issue or PR as a reminder. + +## Questions + +For questions about the contribution process, reach out via the [Astar Discord](https://discord.com/invite/astarnetwork) in the `#documentation` channel, or open a GitHub Discussion. diff --git a/README.md b/README.md index 25124cc253c..004aa260bd0 100644 --- a/README.md +++ b/README.md @@ -205,6 +205,52 @@ git push origin main +## Partner and Tooling Contributions + +If you represent a project, protocol, or developer tool deployed on **Astar EVM** and want it documented here, follow the process below. Direct PRs without a prior approved issue will be closed. + +
+How to Request Inclusion + +### Step 1: Check Eligibility + +Your project must meet all of the following before opening a request: + +* **Live on Astar EVM mainnet** (testnet-only projects are not accepted) +* **Actively maintained** (recent activity required) +* **Not already documented** in these docs +* **Technical and factual** content only (no marketing copy, prices, or APY figures) +* **You are authorized** to submit documentation on behalf of the project + +### Step 2: Open an Integration Request Issue + +Go to the [Issues tab](https://github.com/AstarNetwork/astar-docs/issues/new/choose) and select **New Integration or Tooling Request**. You will be asked to provide: + +* Project name and category +* Live deployment URL on Astar EVM +* Official website and GitHub repository (if open source) +* The section of the docs where your content belongs +* A factual description of what the project does and why it belongs here + +The documentation team will review your request within **5 business days** and respond with one of the following outcomes: + +* **Approved** — you are invited to open a PR with the documentation +* **Needs more information** — the team will ask for clarification +* **Declined** — the request does not meet the criteria; a reason will be given + +### Step 3: Open a Pull Request + +Once your issue is approved, open a PR from a fork of this repository. Your PR must: + +* Reference the approved issue number +* Follow the file structure and style described in [CONTRIBUTING.md](CONTRIBUTING.md) +* Pass the automated CI build (`yarn build`) +* Use the PR checklist template + +See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete documentation standards, writing style guide, and review process. + +
+ ## Working with Images Please import and use the `
` tag instead of `![image]` as this enables smoother translation of docs to other languages (automatic reference to original images, no need to copy images to translated subfolders) and automatically applies some styling such as line breaks. From da0c0b6b37a71a6dcb9613ac424543fb8b9d29d9 Mon Sep 17 00:00:00 2001 From: Juminstock Date: Fri, 5 Jun 2026 10:53:06 -0500 Subject: [PATCH 2/2] fix: address PR review feedback on contribution guide scope and CI wording Replaces all Astar EVM references with Astar Network so chain-agnostic tooling and infra projects are not blocked by the eligibility criteria. Corrects the CI build claim to reflect that automated checks do not run on fork PRs. Updates issue template links to use the chooser URL, softens the title frontmatter requirement to recommended, and updates the Discord invite link. --- .../ISSUE_TEMPLATE/new-integration-request.yml | 8 ++++---- .github/pull_request_template.md | 2 +- CONTRIBUTING.md | 16 ++++++++-------- README.md | 8 ++++---- 4 files changed, 17 insertions(+), 17 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/new-integration-request.yml b/.github/ISSUE_TEMPLATE/new-integration-request.yml index 8ff5e1ef69a..ac2ce6036c3 100644 --- a/.github/ISSUE_TEMPLATE/new-integration-request.yml +++ b/.github/ISSUE_TEMPLATE/new-integration-request.yml @@ -8,7 +8,7 @@ body: value: | Thank you for your interest in being documented in the Astar docs. Please complete all fields accurately. Incomplete requests or projects that do not meet the eligibility criteria will be closed without review. - Before submitting, confirm your project is live on **Astar EVM mainnet**. + Before submitting, confirm your project is live on **Astar Network mainnet**. - type: input id: project-name @@ -42,7 +42,7 @@ body: id: deployment-url attributes: label: Live Deployment URL - description: The URL of your live, Astar EVM mainnet-deployed application + description: The URL of your live Astar Network mainnet deployment or service placeholder: https://yourproject.app validations: required: true @@ -82,7 +82,7 @@ body: id: why-include attributes: label: Why should this be included? - description: Explain the value this documentation provides to Astar EVM developers or users + description: Explain the value this documentation provides to Astar Network developers or users validations: required: true @@ -92,7 +92,7 @@ body: label: Eligibility Checklist description: All items must be confirmed before your request will be reviewed options: - - label: My project is live on Astar EVM mainnet (not testnet only) + - label: My project is live on Astar Network mainnet (not testnet only) required: true - label: My project is actively maintained required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1bbb881fe6b..7eec87da704 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -25,6 +25,6 @@ Closes # ## For New Integration PRs Only -- [ ] The project is live on Astar EVM mainnet +- [ ] The project is live on Astar Network mainnet - [ ] An approved integration request issue exists (Issue #___) - [ ] Page structure follows the existing format for this category diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc35c4230f4..f8b4a95a6cc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,7 +22,7 @@ This section is specifically for teams or individuals who want to get a project, Before opening a request, your project must meet all of the following: -- **Live on mainnet.** Your project must be deployed and functional on Astar EVM. Testnet-only projects are not accepted. +- **Live on mainnet.** Your project must be deployed and functional on Astar Network. Testnet-only projects are not accepted. - **Actively maintained.** The project must show recent activity. Abandoned or deprecated projects will not be added and existing ones may be removed. - **Not a duplicate.** The documentation you are proposing must not already exist or substantially overlap with existing content. - **Factual and technical.** The documentation must describe how to use or integrate the product. Marketing copy, price information, and investment language are not accepted. @@ -34,10 +34,10 @@ New integration documentation follows a proposal-first workflow. A PR submitted #### Stage 1: Open an Integration Request Issue -Use the [New Integration Request](.github/ISSUE_TEMPLATE/new-integration-request.yml) issue template. You will be asked to provide: +Use the [New Integration Request](https://github.com/AstarNetwork/astar-docs/issues/new/choose) issue template. You will be asked to provide: - Project name and category -- Live deployment URL on Astar EVM +- Live deployment or service URL on Astar Network - Official website and GitHub repository (if open source) - The section of the docs where your content belongs - A factual description of what the project does @@ -54,12 +54,12 @@ Once your issue is approved, open a PR that: - References the approved issue number in the description - Follows the file structure and style guide described below -- Passes the automated CI build (`yarn build`) +- Passes a local build check (`yarn build`); a maintainer will verify the build passes before merging - Uses the PR template checklist ### What Happens After Your PR Is Submitted -1. **Automated checks** run first: the build must pass and links must resolve +1. **Build and link checks**: a maintainer will verify the build passes and links resolve 2. **Content review** by the documentation team checks accuracy, tone, and structure 3. **One approval** is required from a team member before merge 4. Once merged, the content appears on [docs.astar.network](https://docs.astar.network) within minutes @@ -83,7 +83,7 @@ If you are unsure where your content belongs, ask in the linked issue before cre Every new page should include: -1. **Frontmatter** with at minimum `sidebar_position` and a `title` +1. **Frontmatter** with at minimum `sidebar_position`; a `title` field is recommended but not required 2. **Overview paragraph** explaining what the page covers and who it is for 3. **Prerequisites** (if applicable) listing what the reader needs before starting 4. **Step-by-step content** using numbered lists for sequential actions @@ -130,7 +130,7 @@ const example = "always add the language" ## Updating Existing Documentation -To report or correct outdated, incorrect, or incomplete content, open a [Content Update Request](.github/ISSUE_TEMPLATE/content-update-request.yml) issue. Include: +To report or correct outdated, incorrect, or incomplete content, open a [Content Update Request](https://github.com/AstarNetwork/astar-docs/issues/new/choose) issue. Include: - The URL or file path of the page in question - The current content that needs changing @@ -150,4 +150,4 @@ If you have not received a response within these timeframes, feel free to leave ## Questions -For questions about the contribution process, reach out via the [Astar Discord](https://discord.com/invite/astarnetwork) in the `#documentation` channel, or open a GitHub Discussion. +For questions about the contribution process, reach out via the [Astar Discord](https://discord.gg/astarnetwork) in the `#documentation` channel, or open a GitHub Discussion. diff --git a/README.md b/README.md index 004aa260bd0..ca4c79fb9eb 100644 --- a/README.md +++ b/README.md @@ -207,7 +207,7 @@ git push origin main ## Partner and Tooling Contributions -If you represent a project, protocol, or developer tool deployed on **Astar EVM** and want it documented here, follow the process below. Direct PRs without a prior approved issue will be closed. +If you represent a project, protocol, or developer tool deployed on **Astar Network** and want it documented here, follow the process below. Direct PRs without a prior approved issue will be closed.
How to Request Inclusion @@ -216,7 +216,7 @@ If you represent a project, protocol, or developer tool deployed on **Astar EVM* Your project must meet all of the following before opening a request: -* **Live on Astar EVM mainnet** (testnet-only projects are not accepted) +* **Live on Astar Network mainnet** (testnet-only projects are not accepted) * **Actively maintained** (recent activity required) * **Not already documented** in these docs * **Technical and factual** content only (no marketing copy, prices, or APY figures) @@ -227,7 +227,7 @@ Your project must meet all of the following before opening a request: Go to the [Issues tab](https://github.com/AstarNetwork/astar-docs/issues/new/choose) and select **New Integration or Tooling Request**. You will be asked to provide: * Project name and category -* Live deployment URL on Astar EVM +* Live deployment or service URL on Astar Network * Official website and GitHub repository (if open source) * The section of the docs where your content belongs * A factual description of what the project does and why it belongs here @@ -244,7 +244,7 @@ Once your issue is approved, open a PR from a fork of this repository. Your PR m * Reference the approved issue number * Follow the file structure and style described in [CONTRIBUTING.md](CONTRIBUTING.md) -* Pass the automated CI build (`yarn build`) +* Pass a local build check (`yarn build`); a maintainer will verify this before merging * Use the PR checklist template See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete documentation standards, writing style guide, and review process.