Skip to content

First Contribution Guide

Welcome! This guide will help you make your first contribution to the Portugal Odyssey platform.

Prerequisites

  • Development environment set up (Local Setup)
  • Git configured
  • Code editor ready

Contribution Workflow

1. Fork and Clone

# Fork the repository on GitLab
# Then clone your fork
git clone https://gitlab.com/your-username/po-platform.git
cd po-platform

2. Create Feature Branch

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

# Or for bug fixes
git checkout -b fix/bug-description

3. Make Changes

  • Write code following project standards
  • Add tests for new functionality
  • Update documentation if needed

4. Test Locally

# Run tests
npm test

# Or for specific service
cd services/[service-name]
npm test

# Start development stack
make dev

5. Commit Changes

# Stage changes
git add .

# Commit with descriptive message
git commit -m "feat: add new feature description"

Commit Message Format: - feat: - New feature - fix: - Bug fix - docs: - Documentation - refactor: - Code refactoring - test: - Tests - chore: - Maintenance

6. Push and Create Merge Request

# Push to your fork
git push origin feature/your-feature-name

Then create a merge request on GitLab: 1. Go to your fork on GitLab 2. Click "Merge Requests" → "New Merge Request" 3. Select your branch 4. Fill out the merge request template 5. Request review

Code Standards

TypeScript/JavaScript

  • Use TypeScript for new code
  • Follow ESLint rules
  • Use Prettier for formatting
  • Write meaningful variable names

NestJS Services

  • Follow NestJS best practices
  • Use dependency injection
  • Add proper error handling
  • Include API documentation

React Frontend

  • Use functional components
  • Follow React hooks best practices
  • Use TypeScript
  • Follow component structure

Testing Requirements

Unit Tests

cd services/[service-name]
npm test

Integration Tests

npm run test:integration

E2E Tests

npm run test:e2e

Documentation

When adding new features:

  1. Update service README - Document new endpoints/features
  2. Add API docs - Document new APIs
  3. Update architecture docs - If architecture changes
  4. Add examples - Code examples for complex features

Review Process

  1. Automated checks - CI/CD pipeline runs automatically
  2. Code review - Team member reviews your changes
  3. Testing - Reviewer tests your changes
  4. Approval - After approval, changes are merged

Common First Contributions

Documentation

  • Fix typos
  • Improve clarity
  • Add examples
  • Update outdated information

Bug Fixes

  • Fix reported bugs
  • Improve error messages
  • Add missing error handling

Small Features

  • Add utility functions
  • Improve existing features
  • Add tests

Getting Help

  • Questions? Ask in merge request comments
  • Stuck? Check Troubleshooting Guide
  • Need clarification? Tag maintainers in merge request

See Also