Aller au contenu principal

Contributing to JifiJs

JifiJs Lion Logo

Thank you for your interest in contributing to JifiJs! 🎉

We welcome contributions from developers of all experience levels. Whether you're fixing a bug, adding a feature, or improving documentation, your help makes JifiJs better for everyone.

🌟 Ways to Contribute​

1. Report Bugs 🐛​

Found a bug? Please report it!

  • Check existing issues first to avoid duplicates
  • Use the bug report template on GitHub
  • Include reproduction steps and environment details
  • Add relevant logs or screenshots

Report a Bug →

2. Suggest Features 💡​

Have an idea to make JifiJs better?

  • Search existing feature requests first
  • Describe the use case and expected benefit
  • Consider backward compatibility
  • Be open to discussion on implementation

Request a Feature →

3. Improve Documentation 📝​

Documentation improvements are always welcome:

  • Fix typos or unclear explanations
  • Add examples and use cases
  • Improve code snippets
  • Translate to other languages

4. Submit Code 🔧​

Ready to write code? Great! Follow the guidelines below.

🚀 Getting Started​

Prerequisites​

Before contributing, ensure you have:

  • Node.js 18+ installed
  • npm or yarn package manager
  • Git for version control
  • MongoDB for database testing (optional, can use Docker)
  • Redis for caching tests (optional, can use Docker)

Fork and Clone​

  1. Fork the repository on GitHub
  2. Clone your fork locally:
git clone https://github.com/YOUR_USERNAME/jifijs.git
cd jifijs
  1. Add upstream remote:
git remote add upstream https://github.com/mrnjifanda/jifijs.git

Install Dependencies​

npm install

Set Up Environment​

Copy the example environment file:

cp .env.example .env

Update .env with your local configuration (MongoDB, Redis, etc.)

🏗️ Development Workflow​

1. Create a Feature Branch​

Always create a new branch for your work:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

Branch naming conventions:

  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • refactor/ - Code refactoring
  • test/ - Adding or updating tests

2. Make Your Changes​

Write clean, maintainable code that follows our standards:

  • Use TypeScript with strict mode
  • Follow existing code style and patterns
  • Write meaningful commit messages
  • Add tests for new features
  • Update documentation as needed

3. Test Your Changes​

Run the test suite to ensure nothing breaks:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Check test coverage
npm run test:coverage

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

4. Commit Your Changes​

Write clear, descriptive commit messages:

git add .
git commit -m "feat: add user profile caching"

Commit message format:

<type>: <subject>

<body (optional)>

<footer (optional)>

Types:

  • feat - New feature
  • fix - Bug fix
  • docs - Documentation changes
  • style - Code style changes (formatting, semicolons, etc.)
  • refactor - Code refactoring
  • test - Adding or updating tests
  • chore - Build process or auxiliary tool changes

Examples:

feat: add email verification for new users
fix: resolve token expiration issue in authentication
docs: update installation guide with Docker setup
refactor: simplify user service error handling
test: add unit tests for file upload service

5. Push and Create Pull Request​

Push your changes and create a PR:

git push origin feature/your-feature-name

Then open a Pull Request on GitHub with:

  • Clear title describing the change
  • Description of what changed and why
  • Reference to related issues (e.g., "Fixes #123")
  • Screenshots for UI changes (if applicable)

📋 Code Standards​

TypeScript Guidelines​

// ✅ Good: Clear types and interfaces
interface UserProfile {
  id: string;
  email: string;
  createdAt: Date;
}

async function getUserProfile(userId: string): Promise<UserProfile> {
  // Implementation
}

// ❌ Bad: Using 'any' or missing types
async function getUserProfile(userId) {
  // Implementation
}

Naming Conventions​

  • Classes: PascalCase (UserService, AuthController)
  • Functions/Methods: camelCase (getUser, validateEmail)
  • Constants: UPPER_SNAKE_CASE (MAX_RETRY_ATTEMPTS)
  • Interfaces: PascalCase with 'I' prefix (IUserRepository)
  • Files: kebab-case (user-service.ts, auth-controller.ts)

Code Style​

  • Use 2 spaces for indentation
  • Use single quotes for strings
  • Add semicolons at the end of statements
  • Keep line length under 120 characters
  • Add JSDoc comments for public APIs
/**
 * Validates user email address
 * @param email - The email address to validate
 * @returns True if email is valid, false otherwise
 */
function validateEmail(email: string): boolean {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}

🧪 Testing Guidelines​

Writing Tests​

  • Write tests for all new features
  • Maintain or improve code coverage
  • Use descriptive test names
  • Test edge cases and error scenarios
describe('UserService', () => {
  describe('createUser', () => {
    it('should create a new user with valid data', async () => {
      // Test implementation
    });

    it('should throw error when email already exists', async () => {
      // Test implementation
    });

    it('should hash password before saving', async () => {
      // Test implementation
    });
  });
});

Test Structure​

tests/
├── unit/          # Unit tests for individual functions/methods
├── integration/   # Integration tests for API endpoints
└── e2e/          # End-to-end tests for complete workflows

📚 Documentation Guidelines​

When updating documentation:

Code Documentation​

  • Add JSDoc comments for public APIs
  • Include parameter descriptions and return types
  • Provide usage examples

Markdown Documentation​

  • Use clear, concise language
  • Include code examples
  • Add screenshots when helpful
  • Keep formatting consistent

🔍 Pull Request Review Process​

  1. Automated checks run on your PR (tests, linting)
  2. Maintainer review within 48 hours
  3. Feedback and discussion if changes needed
  4. Approval and merge once ready

What We Look For​

  • ✅ Code quality and style
  • ✅ Test coverage
  • ✅ Documentation updates
  • ✅ No breaking changes (without discussion)
  • ✅ Performance considerations

🎯 Priority Areas​

We especially welcome contributions in these areas:

  1. Test Coverage - Improving test coverage for existing code
  2. Documentation - Better examples, guides, and API docs
  3. Performance - Optimizations and benchmarks
  4. Bug Fixes - Resolving open issues
  5. TypeScript Types - Improving type definitions

❓ Questions?​

Need help with your contribution?

🙏 Recognition​

All contributors are recognized in our:

  • README contributors section
  • Release notes for their contributions
  • GitHub contributors page

📜 Code of Conduct​

We expect all contributors to:

  • Be respectful and inclusive
  • Provide constructive feedback
  • Focus on what's best for the community
  • Show empathy towards others

📄 License​

By contributing to JifiJs, you agree that your contributions will be licensed under the MIT License.

JifiJs

Ready to Contribute?

Join our community of contributors and help make JifiJs better!