Skip to main content

Contributing

Guidelines for contributing to PBS Knowledge.

Getting Started​

Prerequisites​

  • Node.js 20.x
  • Docker and Docker Compose
  • Git
  • VS Code (recommended)

Setup​

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/pbs_knowledge.git
    cd pbs_knowledge
  3. Add upstream remote: 
    git remote add upstream https://github.com/cosanlab/pbs_knowledge.git
  4. Install dependencies: 
    npm install
    cd backend && npm install
    cd ../frontend && npm install
  5. Copy environment file: 
    cp .env.example .env
  6. Start development: 
    docker compose -f docker-compose.hybrid.yml -f docker-compose.dev.yml up -d

Development Workflow​

Creating a Branch​

# Update main
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

Branch Naming​

Use descriptive branch names:

  • feature/add-milestone-reminders
  • fix/publication-sync-error
  • docs/update-api-reference
  • refactor/simplify-auth-flow

Making Changes​

  1. Make your changes
  2. Write/update tests
  3. Update documentation if needed
  4. Run linting and tests

Committing​

Write clear commit messages:

feat: add email notification for milestone deadlines

- Add reminder job to milestone worker
- Create email template for deadline reminders
- Configure reminder schedule in milestone settings

Follow conventional commits:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation
  • style: - Formatting
  • refactor: - Code restructure
  • test: - Tests
  • chore: - Maintenance

Testing​

Run tests before submitting:

# Backend tests
cd backend && npm run test:run

# Frontend tests
cd frontend && npm run test:run

# Type checking
cd frontend && npm run check
cd backend && npm run typecheck

# Linting
npm run lint

Creating a Pull Request​

  1. Push your branch: 
    git push origin feature/your-feature-name
  2. Go to GitHub and create a PR
  3. Fill in the PR template
  4. Request review

Code Standards​

TypeScript​

  • Use TypeScript for all new code
  • Define types for function parameters and returns
  • Avoid any type when possible
  • Use interfaces for object shapes
interface PersonData {
  firstName: string;
  lastName: string;
  email?: string;
}

function createPerson(data: PersonData): Promise<Person> {
  // ...
}

Svelte​

  • Use Svelte 5 runes where appropriate
  • Keep components focused and small
  • Use TypeScript in script blocks
  • Follow Svelte style guidelines
<script lang="ts">
  interface Props {
    name: string;
    count?: number;
  }

  let { name, count = 0 }: Props = $props();
</script>

Styling​

  • Use Tailwind CSS classes
  • Follow existing color scheme
  • Ensure responsive design
  • Maintain accessibility

Backend​

  • Follow service pattern
  • Use descriptive route names
  • Validate all inputs
  • Handle errors appropriately
// Good
fastify.get('/api/people/:type/:id', async (request, reply) => {
  const { type, id } = request.params;
  const person = await personService.getById(type, id);
  if (!person) {
    return reply.code(404).send({ error: 'Person not found' });
  }
  return person;
});

Testing Guidelines​

Unit Tests​

  • Test individual functions
  • Mock external dependencies
  • Cover edge cases
describe('PersonService', () => {
  it('should return person by id', async () => {
    const person = await service.getById('Faculty', 'abc123');
    expect(person.first_name).toBe('John');
  });
});

Integration Tests​

  • Test API endpoints
  • Use test database
  • Clean up test data

Test Files​

  • Place tests near source files
  • Name with .test.ts or .spec.ts
  • Use descriptive test names

Documentation​

Code Comments​

  • Comment complex logic
  • Use JSDoc for public functions
  • Keep comments up to date
/**
 * Calculate degree progress for a student.
 * @param studentId - The student's ID
 * @param degreeId - The target degree ID
 * @returns Progress object with completion percentage
 */
async function calculateProgress(studentId: string, degreeId: string): Promise<Progress> {
  // ...
}

README Updates​

Update documentation for:

  • New features
  • Configuration changes
  • API changes
  • Breaking changes

Pull Request Guidelines​

PR Description​

Include:

  • What the PR does
  • Why the change is needed
  • How to test it
  • Screenshots (for UI changes)

PR Checklist​

  • Code follows style guidelines
  • Tests pass
  • Documentation updated
  • No console.log statements
  • No commented-out code
  • Responsive design verified

Code Review​

  • Respond to feedback promptly
  • Explain reasoning for decisions
  • Make requested changes
  • Request re-review when ready

Release Process​

Releases are handled by maintainers:

  1. Version bump in package.json
  2. Update CHANGELOG
  3. Create release tag
  4. Deploy to production

Getting Help​

  • Questions: Open a discussion on GitHub
  • Bugs: Open an issue with reproduction steps
  • Features: Open an issue describing the feature
  • Security: Email maintainers directly

Code of Conduct​

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help others learn and grow
  • Report unacceptable behavior