Skip to content

Commit 19feabb

Browse files
zandkozandko
committed
docs: Add development guide, pull request template, and issue template
- Created DEVELOPMENT.md to provide guidance for setting up the development environment and contribution guidelines. - Added a pull request template to standardize PR submissions. - Introduced a bug report issue template to streamline issue reporting. - Implemented GitHub workflows for automatic contributor updates and release management.
1 parent 041189d commit 19feabb

File tree

5 files changed

+341
-0
lines changed

5 files changed

+341
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
name: Bug report
3+
about: Create a report to help us improve
4+
title: "[BUG]"
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
**Describe the bug**
10+
A clear and concise description of what the bug is.
11+
12+
**To Reproduce**
13+
Steps to reproduce the behavior:
14+
15+
1. ...
16+
2. ...
17+
3. ...
18+
19+
**Expected behavior**
20+
A clear and concise description of what you expected to happen.
21+
22+
**Environment**
23+
24+
- Node version:
25+
- npm/yarn/pnpm version:
26+
- OS:
27+
- Package version:
28+
29+
**Additional context**
30+
Add any other context about the problem here.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
## Description
2+
3+
<!-- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. -->
4+
5+
Fixes # (issue)
6+
7+
## Type of change
8+
9+
<!-- Please delete options that are not relevant. -->
10+
11+
- [ ] Bug fix (non-breaking change which fixes an issue)
12+
- [ ] New feature (non-breaking change which adds functionality)
13+
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
14+
- [ ] Documentation update
15+
16+
## Checklist
17+
18+
- [ ] My code follows the style guidelines of this project
19+
- [ ] I have performed a self-review of my own code
20+
- [ ] I have added tests that prove my fix is effective or that my feature works
21+
- [ ] The title of my pull request follows the [conventional commits](https://www.conventionalcommits.org/) standard
22+
- [ ] Changes have been documented in the README/documentation (if applicable)

‎.github/workflows/contributors.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Contributors
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
jobs:
10+
update-contributors:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
with:
15+
fetch-depth: 0
16+
17+
- name: Generate Contributors
18+
uses: BobAnkh/add-contributors@master
19+
with:
20+
CONTRIBUTOR: '## 👥 Contributors'
21+
COLUMN_PER_ROW: '6'
22+
ACCESS_TOKEN: ${{secrets.GITHUB_TOKEN}}
23+
IMG_WIDTH: '100'
24+
FONT_SIZE: '14'
25+
PATH: README.md
26+
COMMIT_MESSAGE: 'docs(README): update contributors'
27+
AVATAR_SHAPE: round

‎.github/workflows/release.yml‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
name: Release
2+
3+
on:
4+
release:
5+
types: [created]
6+
7+
jobs:
8+
verify:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
- uses: actions/setup-node@v4
13+
with:
14+
node-version: 22.x
15+
- uses: pnpm/action-setup@v3
16+
with:
17+
version: 8
18+
19+
- name: Get package info
20+
id: package
21+
uses: codex-team/action-nodejs-package-info@v1
22+
23+
- name: Check version match
24+
run: |
25+
TAG_VERSION="${GITHUB_REF#refs/tags/v}"
26+
PACKAGE_VERSION="${{ steps.package.outputs.version }}"
27+
28+
if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then
29+
echo "Error: Tag version ($TAG_VERSION) does not match package.json version ($PACKAGE_VERSION)"
30+
exit 1
31+
fi
32+
33+
echo "✅ Version in package.json matches GitHub tag"
34+
35+
test:
36+
runs-on: ubuntu-latest
37+
needs: verify
38+
steps:
39+
- uses: actions/checkout@v4
40+
- uses: actions/setup-node@v4
41+
with:
42+
node-version: 22.x
43+
- uses: pnpm/action-setup@v3
44+
with:
45+
version: 8
46+
47+
- name: Get pnpm store directory
48+
id: pnpm-cache
49+
shell: bash
50+
run: |
51+
echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
52+
53+
- uses: actions/cache@v4
54+
name: Setup pnpm cache
55+
with:
56+
path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
57+
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
58+
restore-keys: |
59+
${{ runner.os }}-pnpm-store-
60+
61+
- name: Install dependencies
62+
run: pnpm install
63+
64+
- name: Lint
65+
run: pnpm lint
66+
67+
- name: Build
68+
run: pnpm build
69+
70+
- name: Run tests
71+
run: pnpm test || echo "No tests found, skipping test step"
72+
73+
publish:
74+
runs-on: ubuntu-latest
75+
needs: test
76+
steps:
77+
- uses: actions/checkout@v4
78+
with:
79+
fetch-depth: 0
80+
81+
- uses: actions/setup-node@v4
82+
with:
83+
node-version: 22.x
84+
registry-url: 'https://registry.npmjs.org'
85+
86+
- uses: pnpm/action-setup@v3
87+
with:
88+
version: 8
89+
90+
- name: Get pnpm store directory
91+
id: pnpm-cache
92+
shell: bash
93+
run: |
94+
echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
95+
96+
- uses: actions/cache@v4
97+
name: Setup pnpm cache
98+
with:
99+
path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
100+
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
101+
restore-keys: |
102+
${{ runner.os }}-pnpm-store-
103+
104+
- name: Install dependencies
105+
run: pnpm install
106+
107+
- name: Build
108+
run: pnpm build
109+
110+
- name: Generate changelog
111+
id: changelog
112+
uses: metcalfc/[email protected]
113+
with:
114+
myToken: ${{ secrets.GITHUB_TOKEN }}
115+
116+
- name: Update release with changelog
117+
uses: tubone24/[email protected]
118+
env:
119+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
120+
with:
121+
release_name: ${{ github.event.release.tag_name }}
122+
body: ${{ steps.changelog.outputs.changelog }}
123+
124+
- name: Publish to NPM
125+
run: pnpm publish --no-git-checks
126+
env:
127+
NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
128+
129+
- name: Notify success
130+
uses: rjstone/discord-webhook-notify@v1
131+
if: success()
132+
with:
133+
severity: info
134+
details: |
135+
Version ${{ github.event.release.tag_name }} has been successfully published to NPM! 🎉
136+
See the release here: ${{ github.event.release.html_url }}
137+
webhookUrl: ${{ secrets.DISCORD_WEBHOOK }}
138+
continue-on-error: true

‎DEVELOPMENT.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Development Guide
2+
3+
This document provides guidance for developers contributing to this project and details the release process.
4+
5+
## Setting Up Development Environment
6+
7+
1. Clone the repository:
8+
9+
```bash
10+
git clone https://github.com/zandko/mcp-use.git
11+
cd mcp-use
12+
```
13+
14+
2. Install dependencies:
15+
16+
```bash
17+
pnpm install
18+
```
19+
20+
> **Note**: This project requires Node.js version 22 or higher.
21+
22+
3. Build the project:
23+
24+
```bash
25+
pnpm build
26+
```
27+
28+
4. Watch for changes during development:
29+
```bash
30+
pnpm watch
31+
```
32+
33+
## Contribution Guidelines
34+
35+
### Commit Messages
36+
37+
We follow [Conventional Commits](https://www.conventionalcommits.org/) for our commit messages:
38+
39+
- `feat:` - A new feature
40+
- `fix:` - A bug fix
41+
- `docs:` - Documentation only changes
42+
- `style:` - Changes that do not affect the meaning of the code
43+
- `refactor:` - A code change that neither fixes a bug nor adds a feature
44+
- `perf:` - A code change that improves performance
45+
- `test:` - Adding missing tests or correcting existing tests
46+
- `chore:` - Changes to the build process or auxiliary tools
47+
48+
### Pull Request Process
49+
50+
1. Fork the repository
51+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
52+
3. Commit your changes (`git commit -m 'feat: add some amazing feature'`)
53+
4. Push to the branch (`git push origin feature/amazing-feature`)
54+
5. Open a Pull Request
55+
56+
## Release Process
57+
58+
### Automated Release Workflow
59+
60+
We use GitHub Actions to automate our release process, connecting GitHub Releases with npm publishing.
61+
62+
#### For Maintainers
63+
64+
1. **Prepare for Release**:
65+
66+
Update the version in `package.json` using one of these commands:
67+
68+
```bash
69+
# For patch releases (0.0.x) - Bug fixes
70+
pnpm run release
71+
72+
# For minor releases (0.x.0) - New features
73+
pnpm run release:minor
74+
75+
# For major releases (x.0.0) - Breaking changes
76+
pnpm run release:major
77+
```
78+
79+
This will:
80+
81+
- Update the version in package.json
82+
- Create a git tag
83+
- Push the changes and tag to GitHub
84+
85+
2. **Create GitHub Release**:
86+
87+
- Go to GitHub repository → "Releases" → "Draft a new release"
88+
- Choose the tag that was just created
89+
- Fill in release notes detailing what's new, fixes, and any breaking changes
90+
- Click "Publish release"
91+
92+
3. **Automated Publishing**:
93+
94+
The GitHub Action will automatically:
95+
96+
- Verify the package version matches the GitHub tag
97+
- Run linting and build checks
98+
- Generate a changelog from commits since the last release
99+
- Update the GitHub release with the changelog
100+
- Publish to npm with the version from package.json
101+
- Update the Contributors list in the README
102+
- Send a notification upon successful publish (if configured)
103+
104+
### Setting Up Automation (For Repository Owners)
105+
106+
To set up automated publishing:
107+
108+
1. Generate an NPM access token:
109+
110+
- Go to npmjs.com → User Settings → Access Tokens
111+
- Create a new token with "Automation" type and publish permissions
112+
113+
2. Add the token to GitHub repository secrets:
114+
115+
- Go to your GitHub repository → Settings → Secrets → Actions
116+
- Add a new secret named `NPM_TOKEN` with the value of your NPM token
117+
118+
3. (Optional) Discord notifications:
119+
- Create a Discord webhook in your server
120+
- Add the webhook URL as a GitHub repository secret named `DISCORD_WEBHOOK`
121+
122+
## Updating Contributors
123+
124+
Contributors are automatically updated in the README.md file whenever a push is made to the main branch, using the [BobAnkh/add-contributors](https://github.com/BobAnkh/add-contributors) GitHub Action.

0 commit comments

Comments
 (0)