Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
296 lines (200 loc) · 5.76 KB

CONTRIBUTING.md

File metadata and controls

296 lines (200 loc) · 5.76 KB

Contributing Guidelines

Welcome to the ByteProgramming Team!

Please read these guidelines carefully before making any contributions.

All contributions MUST follow these rules or they will be rejected.



🌍 Language Requirements

ALL code MUST be written in English, this includes:

  • ✅ Variable names, function names, class names
  • ✅ Comments and documentation
  • ✅ Commit messages
  • ✅ Issue and PR descriptions
  • ✅ All written content in the codebase

No exceptions. Code not in English will be rejected.



💻 Code Standards

1. Documentation

All code MUST be properly documented using the standard documentation format for the technology used in the project. Documentation must include:

  • Function/method purpose
  • Parameters and their types
  • Return values
  • Exceptions/errors thrown
  • Usage examples when necessary

2. Best Practices

Follow industry-standard best practices:

  • ✅ DRY (Don't Repeat Yourself)
  • ✅ SOLID principles
  • ✅ Clean Code principles
  • ✅ Separation of Concerns
  • ✅ Proper error handling
  • ✅ Security best practices
  • ✅ Performance optimization

3. Code Quality

  • Use meaningful names for variables and functions
  • Keep functions small and focused
  • Follow the project's linting rules
  • Remove commented-out code
  • Remove debugging statements
  • Use constants instead of magic numbers


📚 Documentation Requirements

Code Documentation

Every function, method, and class MUST have documentation following the standard format of the technology used in the project.

README Updates

Update the README.md when:

  • Adding new features
  • Changing configuration or setup
  • Modifying dependencies
  • Changing APIs or interfaces

API Documentation

Document all API endpoints with:

  • Endpoint URL and HTTP method
  • Request parameters and body
  • Authentication requirements


📝 Commit Message Convention

We use Conventional Commits for all commit messages.

Format

<type>(<scope>): <subject>

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code formatting (no logic changes)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding or updating tests
  • chore: Maintenance tasks (dependencies, build, etc.)
  • ci: CI/CD changes
  • revert: Revert a previous commit

Rules

  • Use lowercase for type and scope
  • Keep subject under 50 characters
  • Don't end with a period
  • Use imperative mood ("add" not "added")
  • Reference issues in the footer when applicable


🌿 Branch Naming Convention

Format

<type>/<issue-number>-<short-description>

Types

  • feature/ - New features
  • fix/ - Bug fixes
  • hotfix/ - Urgent production fixes
  • refactor/ - Code refactoring
  • docs/ - Documentation changes
  • test/ - Test-related changes
  • chore/ - Maintenance tasks

Example

feature/123-user-authentication
fix/456-login-validation-error
docs/789-update-api-docs

Rules

  • Use lowercase and hyphens (kebab-case)
  • Include issue number when applicable
  • Keep description short but descriptive


🐛 Issue Guidelines

Before starting work, create an issue using this structure:

### 1. Task Type

- [ ] 🐞 Bug
- [ ] ✨ Feature
- [ ] 🛠️ Chore/Refactor
- [ ] 📖 Documentation

---

### 2. Context & Problem to Solve

[Describe the problem or feature request]

---

### 3. Acceptance Criteria

- [ ] Given [context], when [action], then [expected result]
- [ ] [Additional criteria...]


🔀 Pull Request Guidelines

PR Structure

All PRs MUST follow this template:

### 1. What problem does this PR solve?

Closes: #[ISSUE_NUMBER]

---

### 2. Description of Changes

[Detailed description of what changed and why]

---

### 3. How can this be tested

[Step-by-step testing instructions]

**Evidence (Screenshots/GIFs/Videos):**

---

### 4. Author's Checklist

- [ ] My code follows the project's style guides
- [ ] I have run existing tests and they all pass
- [ ] I have added new tests that cover my changes
- [ ] I have updated relevant documentation
- [ ] There is no "WIP" in the title
- [ ] I have reviewed my own changes

PR Title Format

<type>(<scope>) (#issue-number): <description>

PR Requirements

  • ✅ Link to the related issue
  • ✅ Clear description of changes
  • ✅ Testing instructions
  • ✅ Evidence when applicable (screenshots/videos)
  • ✅ All checklist items completed
  • ✅ Code in English
  • ✅ Proper documentation
  • ✅ All tests passing
  • ✅ Lint passing
  • ✅ No debugging code
  • ✅ At least one team member review


🔀 Merge Title Structure

When merging a PR, use this format:

merge (#PR-number): <type>(<scope>): <description>

Use the same types as commit messages: feat, fix, docs, refactor, test, chore, etc.



✅ Testing Requirements

All code changes MUST include tests

  • Unit Tests: Test individual functions/methods
  • Integration Tests: Test component interactions

Testing Guidelines

  • Write tests before or alongside your code
  • Aim for high code coverage (minimum 80%)
  • Test edge cases and error scenarios
  • Use descriptive test names
  • Keep tests independent

All tests MUST pass before submitting a PR.



🚫 What Will Get Your PR Rejected

  • ❌ Code not in English
  • ❌ Missing or inadequate documentation
  • ❌ Not following Conventional Commits
  • ❌ Failing tests or lint errors
  • ❌ Not following the PR template
  • ❌ No issue reference
  • ❌ Poor code quality
  • ❌ Missing tests for new features
  • ❌ Debugging code left in
  • ❌ Not following the standard documentation format for the technology