Skip to content

Commit aa831b6

Browse files
CrazyDubyaCrazyDubya
committed
Add comprehensive CONTRIBUTING.md with development guidelines and contribution workflow
1 parent 975446e commit aa831b6

1 file changed

Lines changed: 370 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 370 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,370 @@
1+
# Contributing to Projects Repository
2+
3+
First off, thank you for considering contributing to this repository! This collection of projects represents a diverse ecosystem of tools, utilities, and experiments, and we welcome contributions of all kinds.
4+
5+
## 📋 Table of Contents
6+
7+
- [Code of Conduct](#code-of-conduct)
8+
- [How Can I Contribute?](#how-can-i-contribute)
9+
- [Getting Started](#getting-started)
10+
- [Development Workflow](#development-workflow)
11+
- [Style Guidelines](#style-guidelines)
12+
- [Project-Specific Guidelines](#project-specific-guidelines)
13+
- [Commit Messages](#commit-messages)
14+
- [Pull Request Process](#pull-request-process)
15+
16+
## 📜 Code of Conduct
17+
18+
This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the repository maintainers.
19+
20+
## 🤝 How Can I Contribute?
21+
22+
### Reporting Bugs
23+
24+
Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:
25+
26+
- **Use a clear and descriptive title**
27+
- **Describe the exact steps to reproduce the problem**
28+
- **Provide specific examples** (code snippets, commands, etc.)
29+
- **Describe the behavior you observed and what you expected**
30+
- **Include screenshots** if applicable
31+
- **Specify your environment** (OS, Python version, dependencies)
32+
33+
### Suggesting Enhancements
34+
35+
Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:
36+
37+
- **Use a clear and descriptive title**
38+
- **Provide a detailed description** of the proposed enhancement
39+
- **Explain why this enhancement would be useful**
40+
- **List any alternative solutions** you've considered
41+
- **Include mockups or examples** if applicable
42+
43+
### Pull Requests
44+
45+
We actively welcome your pull requests:
46+
47+
1. Fork the repo and create your branch from `main`
48+
2. If you've added code that should be tested, add tests
49+
3. Ensure your code follows the existing style
50+
4. Update documentation as needed
51+
5. Issue the pull request with a clear description
52+
53+
## 🚀 Getting Started
54+
55+
### Prerequisites
56+
57+
- Python 3.7 or higher
58+
- Git
59+
- Basic understanding of Python and GitHub workflow
60+
61+
### Initial Setup
62+
63+
```bash
64+
# Fork and clone the repository
65+
git clone https://github.com/YOUR_USERNAME/projects.git
66+
cd projects
67+
68+
# Create a virtual environment (recommended)
69+
python -m venv venv
70+
source venv/bin/activate # On Windows: venv\Scripts\activate
71+
72+
# Install common dependencies
73+
pip install requests rich lxml
74+
75+
# For AI/LLM projects
76+
pip install anthropic torch transformers
77+
78+
# Install development dependencies (if applicable)
79+
pip install pytest black flake8
80+
```
81+
82+
### Running Projects
83+
84+
Each project is standalone. Navigate to the specific project directory and follow its README:
85+
86+
```bash
87+
cd ChatGPTArchive
88+
python chatgptarchive.py
89+
```
90+
91+
## 🔄 Development Workflow
92+
93+
### 1. Create a Branch
94+
95+
```bash
96+
# Update your local main branch
97+
git checkout main
98+
git pull origin main
99+
100+
# Create a feature branch
101+
git checkout -b feature/your-feature-name
102+
103+
# Or for bug fixes
104+
git checkout -b fix/bug-description
105+
```
106+
107+
### 2. Make Your Changes
108+
109+
- Write clear, commented code
110+
- Follow the existing code style
111+
- Add documentation for new features
112+
- Test your changes thoroughly
113+
114+
### 3. Commit Your Changes
115+
116+
```bash
117+
# Stage your changes
118+
git add .
119+
120+
# Commit with a descriptive message
121+
git commit -m "Add feature: description of your changes"
122+
```
123+
124+
### 4. Push and Create PR
125+
126+
```bash
127+
# Push your branch
128+
git push origin feature/your-feature-name
129+
130+
# Then create a Pull Request on GitHub
131+
```
132+
133+
## 🎨 Style Guidelines
134+
135+
### Python Code Style
136+
137+
We follow PEP 8 with some flexibility:
138+
139+
```python
140+
# Good: Clear variable names, proper spacing
141+
def process_conversation_data(input_file, output_dir):
142+
"""Process ChatGPT conversation data and generate reports.
143+
144+
Args:
145+
input_file (str): Path to input JSON file
146+
output_dir (str): Directory for output files
147+
148+
Returns:
149+
dict: Processing statistics
150+
"""
151+
with open(input_file, 'r') as f:
152+
data = json.load(f)
153+
154+
return process_data(data)
155+
156+
# Bad: Unclear names, poor formatting
157+
def pcd(if,od):
158+
f=open(if,'r')
159+
d=json.load(f)
160+
return pd(d)
161+
```
162+
163+
### General Guidelines
164+
165+
- **Use descriptive variable names** - `conversation_count` not `cc`
166+
- **Add docstrings** to functions and classes
167+
- **Comment complex logic** but avoid obvious comments
168+
- **Keep functions focused** - one function, one purpose
169+
- **Limit line length** to 100 characters when practical
170+
- **Use type hints** when it improves clarity
171+
172+
### Documentation Style
173+
174+
- Use Markdown for all documentation
175+
- Include code examples where applicable
176+
- Keep explanations clear and concise
177+
- Update relevant documentation when changing code
178+
179+
## 📁 Project-Specific Guidelines
180+
181+
### AI/LLM Projects
182+
183+
- Always use environment variables for API keys
184+
- Include example `.env.example` files
185+
- Document API rate limits and costs
186+
- Handle API errors gracefully
187+
- Log API interactions for debugging
188+
189+
### File Processing Projects
190+
191+
- Validate input files before processing
192+
- Handle missing files and directories gracefully
193+
- Provide clear error messages
194+
- Support batch processing where applicable
195+
- Don't modify original files unless explicitly intended
196+
197+
### Game Projects
198+
199+
- Keep game logic separate from display logic
200+
- Document game rules clearly
201+
- Include example gameplay in README
202+
- Provide save/load functionality where applicable
203+
- Handle edge cases in game state
204+
205+
### Automation Projects
206+
207+
- Include safety checks (confirm before destructive operations)
208+
- Log all automated actions
209+
- Provide dry-run mode
210+
- Document required permissions
211+
- Handle interruptions gracefully
212+
213+
## 💬 Commit Messages
214+
215+
### Format
216+
217+
```
218+
type(scope): Short description (50 chars or less)
219+
220+
More detailed explanatory text, if necessary. Wrap at 72 characters.
221+
Explain the problem that this commit is solving, and why you chose
222+
this approach.
223+
224+
- Bullet points are okay
225+
- Use present tense: "Add feature" not "Added feature"
226+
- Reference issues: "Fixes #123" or "Relates to #456"
227+
```
228+
229+
### Types
230+
231+
- **feat**: New feature
232+
- **fix**: Bug fix
233+
- **docs**: Documentation changes
234+
- **style**: Code style changes (formatting, etc.)
235+
- **refactor**: Code refactoring
236+
- **test**: Adding or updating tests
237+
- **chore**: Maintenance tasks
238+
239+
### Examples
240+
241+
```
242+
feat(chatgpt): Add sentiment analysis to conversation processor
243+
244+
Implement sentiment analysis using VADER lexicon to analyze
245+
conversation tone and emotional content.
246+
247+
- Add sentiment scoring to each message
248+
- Generate sentiment trends over time
249+
- Update documentation with usage examples
250+
251+
Fixes #42
252+
```
253+
254+
```
255+
fix(mover): Prevent duplicate file processing
256+
257+
Check file hash before moving to prevent processing the same
258+
file multiple times when monitoring directories.
259+
260+
Fixes #15
261+
```
262+
263+
## 🔍 Pull Request Process
264+
265+
### Before Submitting
266+
267+
1. ✅ Test your changes thoroughly
268+
2. ✅ Update documentation (README, docstrings, etc.)
269+
3. ✅ Ensure code follows style guidelines
270+
4. ✅ Add or update tests if applicable
271+
5. ✅ Verify all tests pass
272+
6. ✅ Update CHANGELOG if the project has one
273+
274+
### PR Description Template
275+
276+
```markdown
277+
## Description
278+
Brief description of what this PR does and why.
279+
280+
## Type of Change
281+
- [ ] Bug fix (non-breaking change)
282+
- [ ] New feature (non-breaking change)
283+
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
284+
- [ ] Documentation update
285+
286+
## Changes Made
287+
- List specific changes
288+
- Use bullet points
289+
- Be clear and concise
290+
291+
## Testing
292+
Describe how you tested your changes:
293+
- Test cases run
294+
- Manual testing performed
295+
- Edge cases considered
296+
297+
## Screenshots (if applicable)
298+
Add screenshots to help explain your changes.
299+
300+
## Checklist
301+
- [ ] My code follows the project's style guidelines
302+
- [ ] I have performed a self-review of my code
303+
- [ ] I have commented my code, particularly in hard-to-understand areas
304+
- [ ] I have updated the documentation accordingly
305+
- [ ] My changes generate no new warnings
306+
- [ ] I have added tests that prove my fix is effective or that my feature works
307+
- [ ] New and existing unit tests pass locally with my changes
308+
309+
## Related Issues
310+
Fixes #(issue number)
311+
Related to #(issue number)
312+
```
313+
314+
### Review Process
315+
316+
1. At least one maintainer will review your PR
317+
2. Address any requested changes
318+
3. Once approved, a maintainer will merge your PR
319+
4. Your contribution will be acknowledged in the commit
320+
321+
## 🏷️ Versioning
322+
323+
For projects that use versioning, we follow [Semantic Versioning](https://semver.org/):
324+
325+
- **MAJOR**: Incompatible API changes
326+
- **MINOR**: Backwards-compatible functionality additions
327+
- **PATCH**: Backwards-compatible bug fixes
328+
329+
## 🎯 Priority Areas
330+
331+
We especially welcome contributions in these areas:
332+
333+
### High Priority
334+
- 🐛 Bug fixes and stability improvements
335+
- 📚 Documentation improvements
336+
- ✅ Adding tests to existing projects
337+
- ♿ Accessibility improvements
338+
339+
### Medium Priority
340+
- 🌟 New features for existing projects
341+
- 🔧 Performance optimizations
342+
- 🎨 UI/UX improvements for GUI projects
343+
- 🔐 Security enhancements
344+
345+
### Nice to Have
346+
- 🆕 New standalone projects
347+
- 🔄 Refactoring for better code organization
348+
- 🌍 Internationalization
349+
- 📊 Analytics and metrics
350+
351+
## 💡 Need Help?
352+
353+
- 📖 Check the [README](README.md) and project-specific documentation
354+
- 🔍 Search existing [issues](https://github.com/CrazyDubya/projects/issues)
355+
- 💬 Start a [discussion](https://github.com/CrazyDubya/projects/discussions)
356+
- 📧 Contact the maintainers
357+
358+
## 🙏 Recognition
359+
360+
Contributors are recognized in several ways:
361+
362+
- Listed in the project's contributors
363+
- Mentioned in release notes for significant contributions
364+
- GitHub's automatic contribution tracking
365+
366+
Thank you for contributing to this project! 🎉
367+
368+
---
369+
370+
*These guidelines are adapted from best practices and may evolve as the project grows. Suggestions for improving these guidelines are always welcome!*

0 commit comments

Comments
 (0)