Skip to content

Commit d5e8360

Browse files
JuminstockGunit2481
Juminstock
and
Gunit2481
authored
Improve the doc contribution workflow (#772)
* Update: Improve the contribution workflow * Updated internal members terms to Organization members --------- Co-authored-by: Gaius_sama <[email protected]>
1 parent f4ed119 commit d5e8360

File tree

1 file changed

+185
-63
lines changed

1 file changed

+185
-63
lines changed

‎README.md‎

Lines changed: 185 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -4,113 +4,235 @@ Welcome to Astar Documentation GitHub Repository! 🗂️
44

55
This website is built using [**Docusaurus**](https://docusaurus.io/), a modern static website generator.
66

7-
## How to contribute using a local instance of the Docusaurus engine
7+
## Prerequisites
88

9-
### Method 1:
10-
11-
Make sure `git`, `node` and `yarn` exist as commands in your terminal or code editors like **Visual Studio Code**.
9+
Before you begin, make sure the following tools are installed on your system:
1210

1311
* [**Git**](https://git-scm.com/downloads)
14-
* [**Node.js**](https://nodejs.org/en)
15-
* [**Yarn**](https://yarnpkg.com/)
12+
* [**Node.js**](https://nodejs.org/en) - version 22.17.0 or greater
13+
* [**Yarn**](https://yarnpkg.com/) - version 4.9.2 or greater
14+
15+
You can verify your installations by running:
16+
```bash
17+
git --version
18+
node --version
19+
yarn --version
20+
```
21+
22+
## How to Contribute
23+
24+
Choose your contribution path based on whether you are a member of the Astar Collective Github Organization or an external contributor:
1625

17-
**🔖 NOTE:** Use a Node.js version equal to or greater than `22.17.0` and a Yarn version equal to or greater than `4.9.2`.
26+
<details>
27+
<summary><b>Organization Contributors (Astar Collective)</b></summary>
1828

19-
**Git/Github:** understand what the following commands do:
29+
If you are part of the Astar organization on GitHub and have write access to the repository, follow these steps:
2030

21-
* Managing branches:
31+
### Step 1: Set Up Your Local Environment
32+
33+
Clone the repository and navigate to it:
2234
```bash
35+
git clone https://github.com/astarnetwork/astar-docs
36+
cd astar-docs
37+
```
2338

39+
Ensure you are on the main branch and have the latest version:
40+
```bash
2441
git checkout main
25-
git checkout -b feat/your-new-branch
42+
git pull
43+
```
44+
45+
### Step 2: Create a New Branch
2646

47+
Create a new feature branch for your changes:
48+
```bash
49+
git checkout -b feat/your-feature-name
2750
```
28-
* Commits:
51+
52+
Install dependencies using yarn:
2953
```bash
54+
yarn install
55+
```
3056

31-
git add .
32-
git commit -m "Your-message-here"
57+
**💡 TIP:** Use descriptive branch names like `feat/update-tokenomics` or `fix/broken-links`.
3358

34-
git push -u origin feat/your-new-branch
59+
### Step 3: Make Your Changes
3560

61+
Start the local development server to preview your changes in real-time:
62+
```bash
63+
yarn start
3664
```
3765

38-
* Create a PR on GitHub and be as detailed as possible about your changes.
66+
This command will launch a local server (typically at `http://localhost:3000`) where you can see your changes as you edit the documentation.
3967

40-
**💡 TIP:** Maybe stashing `git stash` and `git stash pop` will be your best friends.
68+
Make your edits to the documentation files. You should be familiar with:
69+
70+
* **Markdown basics:** titles, subtitles, lists, hyperlinks, code blocks
71+
* **File structure:** understanding where different documentation sections are located
72+
73+
### Step 4: Test Your Changes
74+
75+
Before committing, ensure the documentation builds without errors:
76+
```bash
77+
yarn build
78+
```
4179

42-
- Markdown basics:
43-
- titles, subtitles
44-
- lists
45-
- hyperlinks
80+
If the build completes successfully, you are ready to commit your changes.
4681

47-
### Method 2:
82+
### Step 5: Commit and Push Your Changes
4883

49-
Make sure `node` and `yarn` exist as commands in your terminal or VS Code and [**Github Desktop**](https://desktop.github.com/download/) is installed. All the `git` operations described below can also be found within the menu of the desktop application, and common operations are clearly visible on launch.
84+
Add your changes and create a commit with a descriptive message:
85+
```bash
86+
git add .
87+
git commit -m "Description of your changes"
88+
```
5089

51-
**New document / Modify existing document → Submit a PR ✅**
52-
53-
* Get latest version of docs locally
90+
Push your branch to GitHub:
91+
```bash
92+
git push -u origin feat/your-feature-name
93+
```
5494

55-
* Clone repo → `git clone https://github.com/astarnetwork/astar-docs`
56-
* Move inside the repository → `cd astar-docs`
57-
* Make sure you’re on the main branch → `git checkout main`
58-
* Pull the latest version of the docs → `git pull`
59-
* Create a new branch → `git checkout -b feat/new-feature-name-here`
60-
* Install dependencies by running → `yarn` or `yarn install`
95+
**💡 TIP:** If you need to temporarily save your work without committing, use `git stash` and later restore with `git stash pop`.
6196

62-
* Create/update the docs as you please
97+
### Step 6: Create a Pull Request
6398

64-
* Start the local development server by running → `yarn start`
65-
* Add new page/tweaks/etc
66-
* When you’re happy with it, ensure `yarn build` runs without errors
99+
1. Go to https://github.com/astarnetwork/astar-docs
100+
2. Create a new Pull Request from your feature branch to `main`
101+
3. Provide a detailed description of your changes
102+
4. Once the PR is created, CI/CD will automatically generate a unique staging link for review
103+
5. You can monitor the build progress in the Actions tab on GitHub
104+
6. Wait for feedback from the team
67105

68-
* PR and staging environment
106+
</details>
69107

70-
* Commit your changes and push the new branch up to Github
71-
```bash
108+
<details>
109+
<summary><b>External Contributors (Community Members)</b></summary>
72110

73-
git add .
74-
git commit -m "Your-message-here"
75-
76-
git push -u origin feat/your-new-branch
111+
If you are not part of the Astar organization on GitHub, you will need to fork the repository first before making contributions.
77112

78-
```
113+
### Step 1: Fork the Repository
79114

80-
* Create a new PR on Github → https://github.com/astarnetwork/astar-docs
115+
1. Go to https://github.com/astarnetwork/astar-docs
116+
2. Click the **Fork** button in the top-right corner
117+
3. This creates a copy of the repository under your GitHub account
81118

82-
* Once PR is up, **CI/CD** will automatically build you a unique staging link.
83-
* You can view the progress of this on the Actions tab on Github
84-
* Wait for feedback from the team
119+
### Step 2: Set Up Your Local Environment
85120

86-
## Working with images
121+
Clone your forked repository (replace `YOUR-USERNAME` with your GitHub username):
122+
```bash
123+
git clone https://github.com/YOUR-USERNAME/astar-docs
124+
cd astar-docs
125+
```
87126

88-
Please import and use the `<Figure/>` 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.
89-
90-
**🧑🏻‍💻 Example as seen [here](https://github.com/AstarNetwork/astar-docs/blob/d530139ca7a5ab034a783981d313542e02fdfb54/docs/about/token-economics/inflationary-model.md).**
91-
92-
**Top of file:**
127+
Add the original repository as an upstream remote to keep your fork synchronized:
93128
```bash
129+
git remote add upstream https://github.com/astarnetwork/astar-docs
130+
```
94131

95-
import Figure from "/src/components/figure"
132+
### Step 3: Create a New Branch
96133

134+
Ensure you have the latest changes from the original repository:
135+
```bash
136+
git checkout main
137+
git pull upstream main
97138
```
98139

99-
**Within the file:**
140+
Create a new feature branch for your changes:
100141
```bash
101-
102-
<Figure caption="Tokenomics Model" src={require('/docs/about/token-economics/img/tokenomics_1.png').default } width="100%" />
142+
git checkout -b feat/your-feature-name
143+
```
103144

145+
Install dependencies using yarn:
146+
```bash
147+
yarn install
104148
```
105149

106-
* Please use absolute path to image (e.g. `/docs/about/token-economics/img/tokenomics_1.png` instead of `img/tokenomics_1.png`).
150+
### Step 4: Make Your Changes
107151

108-
## Deploy to production
152+
Start the local development server to preview your changes in real-time:
153+
```bash
154+
yarn start
155+
```
109156

110-
When a PR is ready for merge, click the button at the bottom saying **Merge and Close** and then **Confirm**.
157+
This command will launch a local server (typically at `http://localhost:3000`) where you can see your changes as you edit the documentation.
158+
159+
Make your edits to the documentation files. You should be familiar with:
160+
161+
* **Markdown basics:** titles, subtitles, lists, hyperlinks, code blocks
162+
* **File structure:** understanding where different documentation sections are located
163+
164+
### Step 5: Test Your Changes
165+
166+
Before committing, ensure the documentation builds without errors:
167+
```bash
168+
yarn build
169+
```
170+
171+
If the build completes successfully, you are ready to commit your changes.
172+
173+
### Step 6: Commit and Push Your Changes
174+
175+
Add your changes and create a commit with a descriptive message:
176+
```bash
177+
git add .
178+
git commit -m "Description of your changes"
179+
```
180+
181+
Push your branch to your forked repository:
182+
```bash
183+
git push -u origin feat/your-feature-name
184+
```
185+
186+
### Step 7: Create a Pull Request
187+
188+
1. Go to your forked repository on GitHub (https://github.com/YOUR-USERNAME/astar-docs)
189+
2. Click **Compare & pull request**
190+
3. Ensure the base repository is `astarnetwork/astar-docs` and the base branch is `main`
191+
4. Provide a detailed description of your changes
192+
5. Submit the Pull Request
193+
6. Once the PR is created, CI/CD will automatically generate a unique staging link for review
194+
7. You can monitor the build progress in the Actions tab on GitHub
195+
8. Wait for feedback from the Astar team
196+
197+
### Step 8: Keep Your Fork Updated
198+
199+
To keep your fork synchronized with the original repository:
200+
```bash
201+
git checkout main
202+
git pull upstream main
203+
git push origin main
204+
```
205+
206+
</details>
207+
208+
## Working with Images
209+
210+
Please import and use the `<Figure/>` 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.
211+
212+
**🧑🏻‍💻 Example as seen [here](https://github.com/AstarNetwork/astar-docs/blob/d530139ca7a5ab034a783981d313542e02fdfb54/docs/about/token-economics/inflationary-model.md).**
213+
214+
**Top of file:**
215+
```javascript
216+
import Figure from "/src/components/figure"
217+
```
218+
219+
**Within the file:**
220+
```javascript
221+
<Figure caption="Tokenomics Model" src={require('/docs/about/token-economics/img/tokenomics_1.png').default } width="100%" />
222+
```
223+
224+
**Important:** Please use absolute path to image (e.g. `/docs/about/token-economics/img/tokenomics_1.png` instead of `img/tokenomics_1.png`).
111225

112-
After a few minutes you should see your changes updated on the production site at [**Astar Network Documentation**](https://docs.astar.network).
113-
114226
## HELP! Something is broken 🔍
115227

116-
Likely, a broken build got pushed to `main` somehow. Remove the commit from `main` and force push to `main`, reopen PR in a new PR.
228+
Likely, a broken build got pushed to `main` somehow. Remove the commit from `main` and force push to `main`, reopen PR in a new PR.
229+
230+
231+
232+
## Deploy to Production
233+
234+
**For Organization Contributors Only:**
235+
236+
When a PR is ready for merge, click the button at the bottom saying **Merge and Close** and then **Confirm**.
237+
238+
After a few minutes you should see your changes updated on the production site at [**Astar Network Documentation**](https://docs.astar.network).

0 commit comments

Comments
 (0)