Skip to content

Commit b85bd27

Browse files
SatinWukerORIGSatinWukerORIG
committed
set up CI workflows
1 parent 996b416 commit b85bd27

7 files changed

Lines changed: 420 additions & 0 deletions

File tree

‎.github/CI_SETUP.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# CI/CD Setup Documentation
2+
3+
This document describes the Continuous Integration and Continuous Deployment (CI/CD) setup for the Mojo algorithms repository, based on [TheAlgorithms](https://github.com/TheAlgorithms) organization standards.
4+
5+
## Overview
6+
7+
The CI/CD pipeline consists of four main workflows that automate repository maintenance, code quality checks, and documentation generation.
8+
9+
## Workflows Added
10+
11+
### 1. Directory Writer (`directory_writer.yml`)
12+
13+
**Purpose:** Automatically maintains the `DIRECTORY.md` file
14+
15+
**Triggers:**
16+
- Push to `main` branch
17+
- Pull requests to `main` branch
18+
19+
**Actions:**
20+
- Generates an up-to-date list of all `.mojo` files
21+
- Organizes them in a hierarchical structure
22+
- Commits changes automatically (on push events)
23+
24+
**Benefits:**
25+
- No manual maintenance of DIRECTORY.md required
26+
- Always reflects current repository structure
27+
- Improves discoverability of algorithms
28+
29+
### 2. Directory Verifier (`verify_directory.yml`)
30+
31+
**Purpose:** Ensures DIRECTORY.md stays synchronized with repository structure
32+
33+
**Triggers:**
34+
- Pull requests to `main` branch
35+
36+
**Actions:**
37+
- Generates a fresh DIRECTORY.md
38+
- Compares with existing file
39+
- Fails if differences are found
40+
41+
**Benefits:**
42+
- Catches outdated documentation before merge
43+
- Enforces consistency
44+
- Provides clear error messages with diffs
45+
46+
### 3. Linter (`lint.yml`)
47+
48+
**Purpose:** Enforces code quality and naming conventions
49+
50+
**Triggers:**
51+
- Push to `main` branch
52+
- Pull requests to `main` branch
53+
54+
**Checks:**
55+
- No spaces in filenames
56+
- Lowercase with underscores for `.mojo` files
57+
- No trailing whitespace
58+
59+
**Benefits:**
60+
- Consistent file naming across repository
61+
- Cleaner code
62+
- Prevents common formatting issues
63+
64+
### 4. Link Checker (`check_links.yml`)
65+
66+
**Purpose:** Validates all links in markdown files
67+
68+
**Triggers:**
69+
- Pull requests to `main` branch
70+
- Weekly schedule (Mondays at 00:00 UTC)
71+
72+
**Actions:**
73+
- Scans all markdown files
74+
- Tests external links
75+
- Reports broken links
76+
77+
**Benefits:**
78+
- Prevents broken documentation links
79+
- Maintains high documentation quality
80+
- Catches link rot early
81+
82+
## Scripts Added
83+
84+
### `scripts/build_directory_md.py`
85+
86+
Python script that generates the DIRECTORY.md file by:
87+
1. Walking through the repository
88+
2. Finding all files with specified extensions
89+
3. Creating a hierarchical markdown structure
90+
4. Formatting filenames into readable titles
91+
92+
**Usage:**
93+
```bash
94+
python3 scripts/build_directory_md.py Mojo . .mojo > DIRECTORY.md
95+
```
96+
97+
## Configuration Files
98+
99+
### `.github/markdown-link-check-config.json`
100+
101+
Configures the link checker with:
102+
- Timeout settings (20s)
103+
- Retry logic (3 attempts)
104+
- Status code validation
105+
- URL pattern ignoring (localhost)
106+
107+
## Files Created
108+
109+
```
110+
.github/
111+
├── workflows/
112+
│ ├── check_links.yml
113+
│ ├── directory_writer.yml
114+
│ ├── lint.yml
115+
│ ├── verify_directory.yml
116+
│ └── README.md
117+
├── markdown-link-check-config.json
118+
└── CI_SETUP.md (this file)
119+
120+
scripts/
121+
├── build_directory_md.py
122+
└── README.md
123+
124+
DIRECTORY.md (updated)
125+
```
126+
127+
## Permissions
128+
129+
The workflows use minimal permissions:
130+
- `directory_writer.yml`: Requires `contents: write` to commit changes
131+
- Other workflows: Use default read-only permissions
132+
133+
## Integration with TheAlgorithms
134+
135+
These workflows follow the same patterns used across all TheAlgorithms repositories:
136+
- [TheAlgorithms/Python](https://github.com/TheAlgorithms/Python)
137+
- [TheAlgorithms/Java](https://github.com/TheAlgorithms/Java)
138+
- [TheAlgorithms/JavaScript](https://github.com/TheAlgorithms/JavaScript)
139+
- And 40+ other language repositories
140+
141+
## Next Steps
142+
143+
1. **Test the workflows:** Push a commit to trigger the workflows
144+
2. **Monitor Actions tab:** Check that all workflows run successfully
145+
3. **Add more workflows:** Consider adding:
146+
- Mojo syntax checking (when available)
147+
- Performance benchmarking
148+
- Code coverage reporting
149+
- Automated releases
150+
151+
## Troubleshooting
152+
153+
### Directory Writer Not Committing
154+
155+
If the directory writer workflow runs but doesn't commit:
156+
- Check that `DIRECTORY.md` actually changed
157+
- Verify the workflow has `contents: write` permission
158+
- Check the Actions logs for error messages
159+
160+
### Link Checker Failing
161+
162+
If the link checker reports false positives:
163+
- Update `.github/markdown-link-check-config.json`
164+
- Add patterns to `ignorePatterns`
165+
- Adjust timeout or retry settings
166+
167+
### Lint Failures
168+
169+
If lint checks fail:
170+
- Review the error messages in Actions logs
171+
- Fix naming conventions (lowercase, underscores)
172+
- Remove trailing whitespace
173+
- Ensure no spaces in filenames
174+
175+
## References
176+
177+
- [TheAlgorithms/scripts](https://github.com/TheAlgorithms/scripts) - Original scripts repository
178+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
179+
- [Markdown Link Check Action](https://github.com/gaurav-nelson/github-action-markdown-link-check)

‎.github/markdown-link-check-config.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"ignorePatterns": [
3+
{
4+
"pattern": "^http://localhost"
5+
}
6+
],
7+
"replacementPatterns": [],
8+
"httpHeaders": [
9+
{
10+
"urls": ["https://github.com/"],
11+
"headers": {
12+
"Accept-Encoding": "zstd, br, gzip, deflate"
13+
}
14+
}
15+
],
16+
"timeout": "20s",
17+
"retryOn429": true,
18+
"retryCount": 3,
19+
"fallbackRetryDelay": "30s",
20+
"aliveStatusCodes": [200, 206]
21+
}

‎.github/workflows/README.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# GitHub Actions Workflows
2+
3+
This directory contains automated CI/CD workflows for the repository. These workflows are based on [TheAlgorithms](https://github.com/TheAlgorithms) organization's best practices.
4+
5+
## Workflows
6+
7+
### 1. directory_writer.yml
8+
9+
**Trigger:** Push and Pull Request to `main` branch
10+
11+
**Purpose:** Automatically generates and updates the `DIRECTORY.md` file that lists all algorithm implementations.
12+
13+
**What it does:**
14+
- Checks out the repository
15+
- Sets up Python environment
16+
- Runs the `build_directory_md.py` script
17+
- Commits and pushes changes to DIRECTORY.md (on push events only)
18+
19+
### 2. verify_directory.yml
20+
21+
**Trigger:** Pull Request to `main` branch
22+
23+
**Purpose:** Verifies that the `DIRECTORY.md` file is up-to-date with the current repository structure.
24+
25+
**What it does:**
26+
- Generates a new DIRECTORY.md
27+
- Compares it with the existing one
28+
- Fails the check if they differ
29+
- Shows the differences in the workflow logs
30+
31+
### 3. lint.yml
32+
33+
**Trigger:** Push and Pull Request to `main` branch
34+
35+
**Purpose:** Enforces code quality and naming conventions.
36+
37+
**What it does:**
38+
- Checks for files with spaces in names
39+
- Ensures .mojo files use lowercase with underscores
40+
- Checks for trailing whitespace in code and markdown files
41+
42+
### 4. check_links.yml
43+
44+
**Trigger:** Pull Request to `main` branch and weekly schedule (Mondays at 00:00 UTC)
45+
46+
**Purpose:** Validates all links in markdown files to prevent broken links.
47+
48+
**What it does:**
49+
- Scans all markdown files
50+
- Checks if external links are accessible
51+
- Reports broken or unreachable links
52+
53+
## Configuration Files
54+
55+
### markdown-link-check-config.json
56+
57+
Configuration for the link checker workflow:
58+
- Ignores localhost URLs
59+
- Sets timeout and retry policies
60+
- Configures HTTP headers for GitHub URLs
61+
62+
## Adding New Workflows
63+
64+
When adding new workflows, follow these guidelines:
65+
66+
1. Use descriptive names for workflow files
67+
2. Add appropriate triggers (push, pull_request, schedule, etc.)
68+
3. Include comments explaining complex steps
69+
4. Use the latest versions of GitHub Actions
70+
5. Test workflows in a fork before merging
71+
72+
## Permissions
73+
74+
The `directory_writer.yml` workflow requires `contents: write` permission to commit changes. Other workflows use default read permissions.
75+
76+
## Related Scripts
77+
78+
The workflows use scripts from the `/scripts` directory:
79+
- `build_directory_md.py` - Generates the DIRECTORY.md file
80+
81+
See `/scripts/README.md` for more information about these scripts.

‎.github/workflows/check_links.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: check_links
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
schedule:
8+
# Run weekly on Monday at 00:00 UTC
9+
- cron: '0 0 * * 1'
10+
11+
jobs:
12+
check-links:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Checkout repository
16+
uses: actions/checkout@v4
17+
18+
- name: Check links in markdown files
19+
uses: gaurav-nelson/github-action-markdown-link-check@v1
20+
with:
21+
use-quiet-mode: 'yes'
22+
config-file: '.github/markdown-link-check-config.json'

‎.github/workflows/directory_writer.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: directory_writer
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
11+
permissions:
12+
contents: write
13+
14+
jobs:
15+
update-directory:
16+
runs-on: ubuntu-latest
17+
steps:
18+
- name: Checkout repository
19+
uses: actions/checkout@v4
20+
with:
21+
fetch-depth: 0
22+
23+
- name: Set up Python
24+
uses: actions/setup-python@v5
25+
with:
26+
python-version: '3.x'
27+
28+
- name: Generate DIRECTORY.md
29+
run: |
30+
python3 scripts/build_directory_md.py Mojo . .mojo > DIRECTORY.md
31+
32+
- name: Commit changes
33+
run: |
34+
git config --local user.email "github-actions[bot]@users.noreply.github.com"
35+
git config --local user.name "github-actions[bot]"
36+
git add DIRECTORY.md
37+
git diff --quiet && git diff --staged --quiet || git commit -m "docs: update DIRECTORY.md"
38+
39+
- name: Push changes
40+
if: github.event_name == 'push'
41+
uses: ad-m/github-push-action@master
42+
with:
43+
github_token: ${{ secrets.GITHUB_TOKEN }}
44+
branch: ${{ github.ref }}

‎.github/workflows/lint.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: lint
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
11+
jobs:
12+
lint:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Checkout repository
16+
uses: actions/checkout@v4
17+
18+
- name: Check file naming conventions
19+
run: |
20+
# Check for files with spaces in names
21+
if find . -type f -name "* *" | grep -v ".git" | grep -q .; then
22+
echo "Error: Files with spaces found:"
23+
find . -type f -name "* *" | grep -v ".git"
24+
exit 1
25+
fi
26+
27+
# Check for uppercase letters in .mojo files
28+
if find . -type f -name "*.mojo" | grep -E '[A-Z]' | grep -q .; then
29+
echo "Error: .mojo files should use lowercase with underscores:"
30+
find . -type f -name "*.mojo" | grep -E '[A-Z]'
31+
exit 1
32+
fi
33+
34+
- name: Check for trailing whitespace
35+
run: |
36+
if git grep -n '[[:space:]]$' -- '*.mojo' '*.md'; then
37+
echo "Error: Trailing whitespace found"
38+
exit 1
39+
fi

0 commit comments

Comments
 (0)