Skip to content

Commit 74cf2ae

Browse files
SeniorRolesSeniorRoles
committed
docs: add README.md
1 parent 0dad534 commit 74cf2ae

1 file changed

Lines changed: 175 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# GradientHQ Development Standards
2+
3+
This repository serves as the development standards hub for the GradientHQ organization, containing commit message conventions, workflow configurations, and other development standards to ensure code quality and consistency across all organizational repositories.
4+
5+
## Standards Overview
6+
7+
### Currently Configured Standards
8+
9+
- **Commit Message Convention** - Based on Conventional Commits standard
10+
- **Automated Checks** - GitHub Actions workflows
11+
- **Code Quality Assurance** - Unified linting and formatting rules
12+
13+
## Repository Structure
14+
15+
```
16+
.
17+
├── .commitlintrc.json # Commit message convention configuration
18+
├── .github/
19+
│ └── workflows/
20+
│ └── commitlint.yml # Automated commit message check workflow
21+
└── README.md # This standards documentation
22+
```
23+
24+
## Commit Message Convention
25+
26+
### Convention Format
27+
28+
```
29+
<type>: <short description>
30+
31+
[optional detailed description]
32+
33+
[optional footer]
34+
```
35+
36+
### Supported Commit Types
37+
38+
| Type | Description | Example |
39+
|------|-------------|---------|
40+
| `feat` | New feature | `feat: add user login functionality` |
41+
| `fix` | Bug fix | `fix: resolve login page styling issue` |
42+
| `docs` | Documentation update | `docs: update API documentation` |
43+
| `style` | Code formatting | `style: standardize code indentation` |
44+
| `refactor` | Code refactoring | `refactor: restructure user service module` |
45+
| `perf` | Performance optimization | `perf: optimize database query performance` |
46+
| `test` | Test related | `test: add user module unit tests` |
47+
| `chore` | Build/tool changes | `chore: update dependency versions` |
48+
49+
### Convention Requirements
50+
51+
- ✅ Title must not exceed 100 characters
52+
- ✅ Use lowercase or sentence case
53+
- ✅ Must use specified commit types
54+
- ✅ Concisely describe the changes
55+
56+
### Commit Examples
57+
58+
**✅ Good commit message:**
59+
```
60+
feat: add user avatar upload functionality
61+
62+
Implement user avatar upload and preview features, supporting JPG and PNG formats,
63+
with 2MB file size limit, including image compression and error handling.
64+
65+
Closes #123
66+
```
67+
68+
**❌ Non-compliant commit message:**
69+
```
70+
update code
71+
fixed some stuff
72+
WIP
73+
```
74+
75+
## Automated Workflows
76+
77+
### Commitlint Check
78+
79+
- **Trigger**: Every Pull Request creation or update
80+
- **Check Content**: Validates all commit messages against conventions
81+
- **Runtime Environment**: Ubuntu + Node.js 20
82+
- **Failure Handling**: Non-compliant PRs cannot be merged
83+
84+
## Developer Guide
85+
86+
### 1. Local Development Setup
87+
88+
**Install commitlint (recommended):**
89+
```bash
90+
npm install --save-dev @commitlint/{config-conventional,cli}
91+
```
92+
93+
**Configure Git Hook:**
94+
```bash
95+
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'
96+
```
97+
98+
### 2. Daily Development Workflow
99+
100+
1. **Create feature branch**
101+
```bash
102+
git checkout -b feat/new-feature
103+
```
104+
105+
2. **Make standardized commits**
106+
```bash
107+
git commit -m "feat: add new feature description"
108+
```
109+
110+
3. **Create Pull Request**
111+
- Ensure commit messages comply with conventions
112+
- Wait for automated checks to pass
113+
- Request code review
114+
115+
### 3. Commit Message Best Practices
116+
117+
- **Use imperative mood**: "add" not "added"
118+
- **Lowercase first letter**: unless it's a proper noun
119+
- **Describe what changed**: explain what was done, not how
120+
- **Link issues**: use `Closes #123` to link related issues
121+
122+
## Standards Maintenance
123+
124+
### Modifying Standards
125+
126+
1. Create an Issue in this repository to discuss changes
127+
2. Submit a Pull Request to modify configurations
128+
3. After team review and approval, merge changes
129+
4. New standards automatically apply to all repositories
130+
131+
### Standards Extension Roadmap
132+
133+
- [x] Code formatting standards (Prettier/ESLint)
134+
- [ ] Branch naming conventions
135+
- [ ] Pull Request templates
136+
- [ ] Issue templates
137+
- [ ] Code review guidelines
138+
139+
## Getting Help
140+
141+
### Having Issues?
142+
143+
1. **Check documentation**: Review this README and related links first
144+
2. **Search Issues**: Check if similar problems have been discussed
145+
3. **Create Issue**: Describe specific problems and reproduction steps
146+
4. **Contact team**: Seek help in team communication channels
147+
148+
### Have Improvement Suggestions?
149+
150+
1. Create an Issue in this repository
151+
2. Provide detailed description of suggestions and rationale
152+
3. Participate in discussions and solution refinement
153+
4. Submit Pull Request to implement improvements
154+
155+
## Related Resources
156+
157+
- [Conventional Commits Official Documentation](https://www.conventionalcommits.org/)
158+
- [Commitlint Configuration Guide](https://commitlint.js.org/)
159+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
160+
- [Git Best Practices](https://git-scm.com/book/en/v2)
161+
162+
## 📈 Standards Impact
163+
164+
Through unified development standards, we aim to achieve:
165+
166+
- ✅ **Improved Code Quality**: Unified standards and automated checks
167+
- ✅ **Enhanced Collaboration**: Clear commit history and change records
168+
- ✅ **Reduced Maintenance Costs**: Standardized code is easier to maintain
169+
- ✅ **Faster Onboarding**: Clear development processes and standard documentation
170+
171+
---
172+
173+
**Important Notice**: Configurations in this repository affect all repositories in the GradientHQ organization. Please discuss thoroughly and test before making changes.
174+
175+
*Last Updated: 2025*

0 commit comments

Comments
 (0)