Skip to content

Commit 97b3218

Browse files
twentyTwotwentyTwo
committed
docs: update CONTRIBUTING.md with enhanced guidelines and workflow steps
1 parent c8b0f10 commit 97b3218

1 file changed

Lines changed: 296 additions & 31 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 296 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
11
# Contributing to Simple Coding Time Tracker
22

3-
We're excited that you're interested in contributing to VSCode Time Tracker! This document will guide you through the process of setting up the project, making changes, and submitting your contributions.
3+
Thank you for your interest in contributing to Simple Coding Time Tracker! We welcome contributions from developers of all skill levels. This guide will walk you through our development workflow and help you make your first contribution.
4+
5+
## 🚀 Quick Start for Contributors
6+
7+
1. **Fork** the repository to your GitHub account
8+
2. **Clone** your fork and set up the development environment
9+
3. **Create** a feature branch for your changes
10+
4. **Make** your changes and test thoroughly
11+
5. **Submit** a pull request to the `develop` branch for review
12+
13+
**Important:** All pull requests should target the `develop` branch, not `main`. This allows for proper testing before merging to production.
414

515
## Project Structure
616

@@ -26,21 +36,47 @@ vscode-time-tracker/
2636
└── LICENSE # License information
2737
```
2838

29-
## Setting Up the Development Environment
39+
## 🛠️ Setting Up the Development Environment
3040

31-
1. Fork the repository on GitHub.
32-
2. Clone your fork locally:
33-
```
34-
git clone https://github.com/your-username/vsc-ext-coding-time-tracker.git
35-
```
36-
3. Navigate to the project directory:
37-
```
38-
cd vsc-ext-coding-time-tracker
39-
```
40-
4. Install dependencies:
41-
```
42-
npm install
43-
```
41+
### Step 1: Fork the Repository
42+
43+
1. Go to [https://github.com/twentyTwo/vsc-ext-coding-time-tracker](https://github.com/twentyTwo/vsc-ext-coding-time-tracker)
44+
2. Click the **"Fork"** button in the top-right corner
45+
3. This creates a copy of the repository under your GitHub account
46+
47+
### Step 2: Clone Your Fork
48+
49+
```bash
50+
# Clone your forked repository
51+
git clone https://github.com/YOUR-USERNAME/vsc-ext-coding-time-tracker.git
52+
53+
# Navigate to the project directory
54+
cd vsc-ext-coding-time-tracker
55+
56+
# Add the upstream repository (original repo)
57+
git remote add upstream https://github.com/twentyTwo/vsc-ext-coding-time-tracker.git
58+
59+
# Verify remotes
60+
git remote -v
61+
```
62+
63+
You should see:
64+
- `origin` - Your fork (where you push changes)
65+
- `upstream` - Original repo (where you pull updates)
66+
67+
### Step 3: Install Dependencies
68+
69+
```bash
70+
npm install
71+
```
72+
73+
This installs all required packages including TypeScript, webpack, and VSCode extension dependencies.
74+
75+
### Step 4: Open in VS Code
76+
77+
```bash
78+
code .
79+
```
4480

4581
## Compiling the Extension
4682

@@ -112,25 +148,254 @@ To package the extension for distribution:
112148

113149
This will create a `.vsix` file that can be installed in VSCode.
114150

115-
## Making Changes
151+
## 🔄 Development Workflow
116152

117-
1. Create a new branch for your feature or bug fix:
118-
```
119-
git checkout -b feature/your-feature-name
120-
```
121-
2. Make your changes and commit them with a clear, descriptive commit message.
122-
3. Push your changes to your fork:
123-
```
124-
git push origin feature/your-feature-name
125-
```
153+
### Step 1: Sync with Upstream
154+
155+
Before starting work, make sure your fork is up-to-date:
156+
157+
```bash
158+
# Fetch latest changes from upstream
159+
git fetch upstream
160+
161+
# Switch to develop branch
162+
git checkout develop
163+
164+
# Merge upstream changes
165+
git merge upstream/develop
166+
167+
# Push updates to your fork
168+
git push origin develop
169+
```
170+
171+
###📝 Code Style and Guidelines
172+
173+
### TypeScript Best Practices
174+
175+
- **Type Safety:** Always use proper TypeScript types, avoid `any` when possible
176+
- **Naming Conventions:**
177+
- `camelCase` for variables and functions
178+
- `PascalCase` for classes and interfaces
179+
- `UPPER_CASE` for constants
180+
- **File Organization:** Keep related functionality together
181+
- **Error Handling:** Use try-catch blocks and log errors appropriately
182+
183+
### Code Quality Checklist
184+
185+
Before submitting a PR, ensure:
186+
187+
- ✅ **No TypeScript errors:** Run `npm run compile` without errors
188+
- ✅ **Meaningful names:** Variables, functions, and classes have descriptive names
189+
- ✅ **Comments:** Complex logic is explained with comments
190+
- ✅ **No console.logs:** Use the `logger` utility instead
191+
- ✅ **Formatting:** Code follows the existing style in the project
192+
- ✅ **No unused imports:** Clean up unused code and imports
193+
- ✅ **Performance:** Consider performance implications of your changes
194+
195+
### Example Code Style
196+
197+
```typescript
198+
// Good: Clear interface definition with proper types
199+
interface CodingSession {
200+
projectName: string;
201+
branchName: string;
202+
language: string;
203+
duration: number;
204+
timestamp: number;
205+
}
206+
207+
// Good: Well-documented function
208+
/**
209+
* Calculates total coding time for a specific project
210+
* @param projectName The name of the project
211+
* @param startDate Start date for calculation (timestamp)
212+
* @param endDate End date for calculation (timestamp)
213+
* @returns Total time in milliseconds
214+
*/
215+
function calculateProjectTime(
216+
projectName: string,
217+
startDate: number,
218+
endDate: number
219+
): number {
220+
// Implementation here
221+
}
222+
```
223+
224+
## 🎯 What to Contribute
225+
226+
### Good First Issues
227+
228+
Looking for where to start? Check out issues labeled:
229+
- `good first issue` - Perfect for newcomers
230+
- `help wanted` - Areas where we need assistance
231+
- `bug` - Bug fixes are always welcome
232+
233+
### Contribution Ideas
234+
235+
- 🐛 **Bug fixes** - Fix reported bugs or issues you encounter
236+
- ✨ **New features** - Add new functionality (discuss in an issue first)
237+
- 📚 **Documentation** - Improve README, wiki, or code comments
238+
- 🎨 **UI/UX improvements** - Enhance the user interface
239+
- 🧪 **Tests** - Add or improve test coverage
240+
- ♿ **Accessibility** - Improve accessibility features
241+
- 🌍 **Internationalization** - Add language translations
242+
243+
### Before Starting Major Work
244+
245+
For significant changes or new features:
246+
1. **Open an issue first** to discuss your idea
247+
2. Wait for feedback from maintainers
248+
3. This prevents duplicate work and ensures alignment with project goals
126249

127-
## Creating a Pull Request
250+
## 🐛 Reporting Bugs
128251

129-
1. Go to the original repository on GitHub.
130-
2. Click on "Pull requests" and then "New pull request".
131-
3. Select your fork and the branch containing your changes.
132-
4. Fill out the pull request template with a clear description of your changes.
133-
5. Submit the pull request.
252+
Found a bug? Help us fix it!
253+
254+
1. **Check existing issues** - Your bug might already be reported
255+
2. **Create a new issue** with:
256+
- Clear, descriptive title
257+
- Steps to reproduce
258+
- Expected behavior vs actual behavior
259+
- VS Code version and OS
260+
- Extension version
261+
- Screenshots/logs if applicable
262+
263+
## 💬 Questions or Need Help?
264+
265+
- 💬 **GitHub Discussions** - Ask questions and discuss ideas
266+
- 🐛 **GitHub Issues** - Report bugs or request features
267+
- 📖 **Wiki** - Check the [documentation wiki](https://github.com/twentyTwo/vsc-ext-coding-time-tracker/wiki)
268+
- 📧 **Email** - Reach out to maintainers for sensitive issues
269+
270+
## 📜 License
271+
272+
By contributing, you agree that your contributions will be licensed under the MIT License.
273+
274+
## 🙏 Thank You!
275+
276+
Every contribution, no matter how small, helps make Simple Coding Time Tracker better. We appreciate your time and effort in improving this project for the developer community!
277+
278+
Happy coding! 🚀
279+
git checkout -b feature/add-weekly-chart
280+
281+
# Example: Fixing a bug
282+
git checkout -b fix/timer-reset-issue
283+
```
284+
285+
### Step 3: Make Your Changes
286+
287+
1. **Write code** following the project's code style
288+
2. **Test thoroughly** using the methods described below
289+
3. **Commit regularly** with clear, descriptive messages
290+
291+
```bash
292+
# Stage your changes
293+
git add .
294+
295+
# Commit with a meaningful message
296+
git commit -m "Add weekly chart visualization to summary view"
297+
298+
# For multiple commits, use this format:
299+
git commit -m "feat: add weekly chart component"
300+
git commit -m "test: add unit tests for weekly chart"
301+
git commit -m "docs: update README with weekly chart feature"
302+
```
303+
304+
**Commit Message Guidelines:**
305+
- `feat:` - New feature
306+
- `fix:` - Bug fix
307+
- `docs:` - Documentation changes
308+
- `test:` - Adding or updating tests
309+
- `refactor:` - Code refactoring
310+
- `style:` - Formatting changes
311+
- `chore:` - Maintenance tasks
312+
313+
### Step 4: Push to Your Fork
314+
315+
```bash
316+
# Push your feature branch to your fork
317+
git push origin feature/add-weekly-chart
318+
```
319+
320+
If this is your first push on this branch, Git will provide a link to create a pull request.
321+
322+
## 🔀 Creating a Pull Request
323+
324+
### Important: Target the `develop` Branch
325+
326+
**All pull requests must be submitted to the `develop` branch**, not `main`. The `develop` branch is used for testing and integration before merging to production (`main`).
327+
328+
### Steps to Create a PR:
329+
330+
1. **Go to your fork** on GitHub (https://github.com/YOUR-USERNAME/vsc-ext-coding-time-tracker)
331+
2. You'll see a yellow banner saying **"Compare & pull request"** - click it
332+
3. **Verify the base and compare branches:**
333+
- Base repository: `twentyTwo/vsc-ext-coding-time-tracker`
334+
- Base branch: `develop` ⚠️ **Must be develop, not main!**
335+
- Head repository: `YOUR-USERNAME/vsc-ext-coding-time-tracker`
336+
- Compare branch: `feature/your-feature-name`
337+
4. **Fill out the PR template:**
338+
- **Title:** Clear, concise description (e.g., "Add weekly chart visualization")
339+
- **Description:** Explain what changes you made and why
340+
- **Testing:** Describe how you tested your changes
341+
- **Screenshots:** Add screenshots/GIFs if UI changes are involved
342+
5. **Click "Create pull request"**
343+
344+
### PR Description Template:
345+
346+
```markdown
347+
## Description
348+
Brief description of what this PR does.
349+
350+
## Type of Change
351+
- [ ] Bug fix
352+
- [ ] New feature
353+
- [ ] Breaking change
354+
- [ ] Documentation update
355+
356+
## Changes Made
357+
- List key changes
358+
- Be specific about what was added/modified/removed
359+
360+
## Testing Performed
361+
- [ ] Tested in development mode (F5)
362+
- [ ] Tested with packaged extension (.vsix)
363+
- [ ] Tested in light and dark themes
364+
- [ ] Verified no console errors
365+
- [ ] Tested on [OS name and version]
366+
367+
## Screenshots (if applicable)
368+
Add screenshots or GIFs demonstrating the changes.
369+
370+
## Related Issues
371+
Closes #issue_number (if applicable)
372+
```
373+
374+
### What Happens Next?
375+
376+
1. **Automated checks** may run (if configured)
377+
2. **Maintainer review** - I'll review your code and provide feedback
378+
3. **Testing** - Changes will be tested in the `develop` branch
379+
4. **Approval & merge** - Once approved, your PR will be merged to `develop`
380+
5. **Release** - After testing, changes from `develop` will be merged to `main` and released
381+
382+
## 🔄 Keeping Your Fork Updated
383+
384+
If your PR takes time to review, keep your branch updated:
385+
386+
```bash
387+
# Fetch latest changes
388+
git fetch upstream
389+
390+
# Switch to your feature branch
391+
git checkout feature/your-feature-name
392+
393+
# Rebase on top of upstream develop
394+
git rebase upstream/develop
395+
396+
# Force push to your fork (since history changed)
397+
git push --force-with-lease origin feature/your-feature-name
398+
```
134399

135400
## Code Style and Guidelines
136401

0 commit comments

Comments
 (0)