Add contributing guide
This commit is contained in:
Chris Veleris
parent
3148bfd4ab
commit
dc2b8eb35e
3 changed files with 288 additions and 56 deletions
285
.github/CONTRIBUTING.md
vendored
Normal file
285
.github/CONTRIBUTING.md
vendored
Normal file
|
|
@ -0,0 +1,285 @@
|
|||
# Contributing to tududi
|
||||
|
||||
Thank you for your interest in contributing to tududi! This guide will help you get started.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Code of Conduct](#code-of-conduct)
|
||||
- [Getting Started](#getting-started)
|
||||
- [Development Workflow](#development-workflow)
|
||||
- [Code Standards](#code-standards)
|
||||
- [Testing](#testing)
|
||||
- [Database Changes](#database-changes)
|
||||
- [Translations](#translations)
|
||||
- [Pull Request Process](#pull-request-process)
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
Please be respectful and constructive in all interactions. We want to foster an inclusive and welcoming community.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js (v22 or higher recommended)
|
||||
- npm
|
||||
- Git
|
||||
|
||||
### Setup
|
||||
|
||||
1. **Fork and clone the repository**
|
||||
```bash
|
||||
git clone https://github.com/chrisvel/tududi.git
|
||||
cd tududi
|
||||
```
|
||||
|
||||
2. **Install dependencies**
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **Initialize the database**
|
||||
```bash
|
||||
npm run db:init
|
||||
```
|
||||
|
||||
4. **Start the development server**
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
This starts both frontend (http://localhost:8080) and backend (http://localhost:5000)
|
||||
|
||||
5. **Create a test user** (optional)
|
||||
```bash
|
||||
npm run user:create
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Branch Naming
|
||||
|
||||
- `feature/description` - New features
|
||||
- `fix/description` - Bug fixes
|
||||
- `refactor/description` - Code refactoring
|
||||
- `docs/description` - Documentation changes
|
||||
- `test/description` - Test additions or fixes
|
||||
|
||||
### Before You Start
|
||||
|
||||
1. **Check existing issues and discussions** to avoid duplicate work
|
||||
2. **Create or comment on an issue** describing what you plan to work on
|
||||
3. **Create a new branch** from `main`
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
### Development Commands
|
||||
|
||||
```bash
|
||||
# Start development server (frontend + backend)
|
||||
npm start
|
||||
|
||||
# Run frontend only
|
||||
npm run frontend:dev
|
||||
|
||||
# Run backend only
|
||||
npm run backend:dev
|
||||
|
||||
# Run tests
|
||||
npm test # Backend tests
|
||||
npm run test:ui # E2E tests
|
||||
npm run test:coverage # Coverage report
|
||||
|
||||
# Linting and formatting
|
||||
npm run lint # Check all code
|
||||
npm run lint:fix # Auto-fix linting issues
|
||||
npm run format:fix # Auto-format code
|
||||
|
||||
# Database commands
|
||||
npm run db:migrate # Run migrations
|
||||
npm run db:seed # Seed dev data
|
||||
npm run db:reset # Reset database
|
||||
```
|
||||
|
||||
## Code Standards
|
||||
|
||||
### General Rules
|
||||
|
||||
- **TypeScript** for all new code
|
||||
- **ESLint** and **Prettier** are configured - run before committing:
|
||||
```bash
|
||||
npm run lint:fix && npm run format:fix
|
||||
```
|
||||
- Follow existing code style and patterns
|
||||
- Write meaningful variable and function names
|
||||
- Add comments for complex logic
|
||||
|
||||
### Frontend (React + TypeScript)
|
||||
|
||||
- Use functional components with hooks
|
||||
- Keep components small and focused
|
||||
- Use TypeScript interfaces for props
|
||||
- Place new components in `frontend/components/`
|
||||
- Follow existing folder structure
|
||||
|
||||
### Backend (Node.js + Express)
|
||||
|
||||
- Use async/await (no callbacks)
|
||||
- Validate input using middleware
|
||||
- Use Sequelize models for database access
|
||||
- Follow RESTful API conventions
|
||||
- Place routes in `backend/routes/`
|
||||
- Place business logic in `backend/services/`
|
||||
|
||||
### Security
|
||||
|
||||
- **Never** commit secrets, API keys, or credentials
|
||||
- Validate and sanitize all user input
|
||||
- Use parameterized queries (Sequelize handles this)
|
||||
- Follow OWASP best practices
|
||||
|
||||
## Testing
|
||||
|
||||
### Requirements
|
||||
|
||||
- **Bug fixes** must include a test that would have caught the bug
|
||||
- **New features** should include relevant tests
|
||||
- All tests must pass before submitting PR
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Backend unit tests
|
||||
npm run backend:test
|
||||
|
||||
# Frontend tests
|
||||
npm run frontend:test
|
||||
|
||||
# E2E tests
|
||||
npm run test:ui
|
||||
|
||||
# Watch mode (useful during development)
|
||||
npm run test:watch
|
||||
```
|
||||
|
||||
### Writing Tests
|
||||
|
||||
- Place backend tests in `backend/tests/`
|
||||
- Place frontend tests alongside components as `*.test.tsx`
|
||||
- Use descriptive test names
|
||||
- Follow the Arrange-Act-Assert pattern
|
||||
|
||||
## Database Changes
|
||||
|
||||
### Creating Migrations
|
||||
|
||||
If your changes require database schema changes:
|
||||
|
||||
1. **Create a migration**
|
||||
```bash
|
||||
npm run migration:create -- --name your-migration-name
|
||||
```
|
||||
|
||||
2. **Edit the migration file** in `backend/migrations/`
|
||||
|
||||
3. **Test the migration**
|
||||
```bash
|
||||
npm run migration:run # Apply
|
||||
npm run migration:undo # Rollback to test
|
||||
```
|
||||
|
||||
4. **Update Sequelize models** in `backend/models/`
|
||||
|
||||
5. **Include migrations in your PR**
|
||||
|
||||
### Migration Best Practices
|
||||
|
||||
- Make migrations reversible (implement `down` method)
|
||||
- Test both `up` and `down` migrations
|
||||
- Don't modify existing migrations that have been released
|
||||
- Use transactions for data migrations
|
||||
|
||||
## Translations
|
||||
|
||||
tududi supports multiple languages via i18next.
|
||||
|
||||
### Adding/Updating Translations
|
||||
|
||||
1. **Add keys to English** (source of truth):
|
||||
`frontend/locales/en/translation.json`
|
||||
|
||||
2. **Sync translations**
|
||||
```bash
|
||||
npm run translations:sync
|
||||
```
|
||||
|
||||
3. **Check for missing translations**
|
||||
```bash
|
||||
npm run translations:check
|
||||
```
|
||||
|
||||
### Translation Guidelines
|
||||
|
||||
- Use descriptive key names: `task.create.button` not `btn1`
|
||||
- Keep translations concise for UI elements
|
||||
- Don't translate in code - always use translation keys
|
||||
- Include context in comments if meaning is ambiguous
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
### Before Submitting
|
||||
|
||||
1. **Update your branch** with latest `main`
|
||||
```bash
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout your-branch
|
||||
git rebase main
|
||||
```
|
||||
|
||||
2. **Run the pre-push checks**
|
||||
```bash
|
||||
npm run pre-push
|
||||
```
|
||||
This runs linting, formatting, and tests.
|
||||
|
||||
3. **Test your changes thoroughly**
|
||||
- Manual testing in the browser
|
||||
- Run automated tests
|
||||
- Test on different screen sizes (mobile/desktop)
|
||||
|
||||
### Creating the PR
|
||||
|
||||
1. **Push your branch**
|
||||
```bash
|
||||
git push origin your-branch
|
||||
```
|
||||
|
||||
2. **Create Pull Request** on GitHub
|
||||
|
||||
3. **Fill out the PR template** with:
|
||||
- Clear description of changes
|
||||
- Related issue numbers (use `Fixes #123`)
|
||||
- Testing steps
|
||||
- Screenshots (if UI changes)
|
||||
|
||||
4. **Wait for review** - maintainers will review and may request changes
|
||||
|
||||
### PR Requirements
|
||||
|
||||
- ✅ All tests passing
|
||||
- ✅ Code follows style guidelines
|
||||
- ✅ No linting errors
|
||||
- ✅ Meaningful commit messages
|
||||
- ✅ Documentation updated (if needed)
|
||||
- ✅ Migrations included (if database changes)
|
||||
|
||||
## Questions?
|
||||
|
||||
- **General questions**: Use [GitHub Discussions](https://github.com/chrisvel/tududi/discussions)
|
||||
- **Bug reports**: Create an [issue](https://github.com/chrisvel/tududi/issues)
|
||||
- **Feature requests**: Start a [discussion](https://github.com/chrisvel/tududi/discussions/categories/feature-requests)
|
||||
|
||||
---
|
||||
|
||||
Thank you for contributing to tududi! 🎉
|
||||
56
.github/DISCUSSION_TEMPLATE/feature-request.yml
vendored
56
.github/DISCUSSION_TEMPLATE/feature-request.yml
vendored
|
|
@ -1,56 +0,0 @@
|
|||
title: "[Feature Request] "
|
||||
labels: ["enhancement"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for suggesting a new feature!
|
||||
|
||||
**Before submitting, please search existing discussions to see if this feature has already been requested.**
|
||||
|
||||
Please describe your idea below.
|
||||
|
||||
- type: textarea
|
||||
id: problem
|
||||
attributes:
|
||||
label: Problem or Use Case
|
||||
description: What problem would this feature solve? What's your use case?
|
||||
placeholder: "I'm always frustrated when..."
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: solution
|
||||
attributes:
|
||||
label: Proposed Solution
|
||||
description: Describe how you'd like this feature to work
|
||||
placeholder: "I'd like to be able to..."
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: alternatives
|
||||
attributes:
|
||||
label: Alternatives Considered
|
||||
description: Have you considered any alternative solutions or workarounds?
|
||||
placeholder: "I've tried... but it doesn't work because..."
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: textarea
|
||||
id: additional
|
||||
attributes:
|
||||
label: Additional Context
|
||||
description: Any other context, screenshots, or examples?
|
||||
placeholder: Add mockups, screenshots, or links to similar features in other apps
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: checkboxes
|
||||
id: contribution
|
||||
attributes:
|
||||
label: Contribution
|
||||
description: Would you be willing to help implement this feature?
|
||||
options:
|
||||
- label: I'd be willing to submit a PR for this feature
|
||||
required: false
|
||||
3
.github/ISSUE_TEMPLATE/config.yml
vendored
3
.github/ISSUE_TEMPLATE/config.yml
vendored
|
|
@ -6,3 +6,6 @@ contact_links:
|
|||
- name: Questions & Support
|
||||
url: https://github.com/chrisvel/tududi/discussions
|
||||
about: Ask questions and get help from the community
|
||||
- name: Contributing Guide
|
||||
url: https://github.com/chrisvel/tududi/blob/main/.github/CONTRIBUTING.md
|
||||
about: Learn how to contribute to tududi
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue