Contributing to Curtin Capstone Connect

Thank you for your interest in contributing to Curtin Capstone Connect! This document provides guidelines and instructions for contributing to the project.

🎯 How You Can Contribute

Code Contributions

Documentation Contributions

Testing and Quality Assurance

🚀 Getting Started

Prerequisites

Before contributing, ensure you have:

# Required software
Node.js (version 16.0.0 or higher)
npm (version 7.0.0 or higher)
Git
A code editor (VS Code recommended)

Setting Up Your Development Environment

  1. Fork the Repository 
    # Fork on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/capstone-connect.git
cd capstone-connect
  2. Install Dependencies 
    npm install
  3. Set Up the Database 
    npm run setup-db
npm run seed
  4. Create Environment File 
    # Copy example environment file
cp .env.example .env
# Edit .env with your settings
  5. Start Development Server 
    npm run dev
  6. Verify Setup
    • Open browser to http://localhost:1077
    • Test login with default admin credentials
    • Verify all functionality works

Understanding the Codebase

Important: Before making any changes, read CLAUDE.md for critical coding guidelines and patterns.

Key Files and Directories:

capstone-connect/
├── config/config.js          # Application configuration
├── database/                 # Database layer and migrations
├── middleware/               # Express middleware
├── routes/                   # API endpoints
├── public/                   # Frontend assets (HTML, CSS, JS)
├── utils/                    # Utility functions
├── docs/                     # Documentation
└── tests/                    # Test files

📝 Contribution Workflow

1. Choose Your Contribution

Finding Issues:

Creating New Issues:

2. Development Process

Branch Naming Convention:

# Feature branches
feature/user-authentication-improvement
feature/project-search-filters

# Bug fix branches
bugfix/login-error-handling
bugfix/database-connection-timeout

# Documentation branches
docs/api-documentation-update
docs/contributing-guidelines

Making Changes:

  1. Create Feature Branch 
    git checkout -b feature/your-feature-name
  2. Follow Coding Standards 
    // Use consistent formatting
// Follow existing patterns
// Add comments for complex logic
// Use meaningful variable names
  3. Write Tests 
    # Run existing tests
npm test
   
# Add tests for new functionality
# Tests should be in __tests__ directories
  4. Test Your Changes 
    # Test functionality manually
npm run dev
   
# Run automated tests
npm test
   
# Check for linting issues
npm run lint  # (if available)

3. Submitting Changes

Before Submitting:

Creating Pull Request:

  1. Push Your Branch 
    git push origin feature/your-feature-name
  2. Create Pull Request
    • Use the pull request template
    • Provide clear title and description
    • Reference related issues
    • Include screenshots if UI changes
    • Add reviewers if known
  3. Pull Request Template 
    ## Summary
Brief description of changes
   
## Changes Made
- List of specific changes
- Include any breaking changes
   
## Testing
- How the changes were tested
- Include test cases if applicable
   
## Screenshots
(If UI changes)
   
## Related Issues
Fixes #123
Related to #456

🎨 Coding Standards

JavaScript Guidelines

Code Style:

// Use modern ES6+ features
const fetchProjects = async () => {
    try {
        const response = await fetch('/api/projects');
        const projects = await response.json();
        return projects;
    } catch (error) {
        console.error('Failed to fetch projects:', error);
        throw error;
    }
};

// Use meaningful variable names
const authenticatedUser = getAuthenticatedUser();
const projectSubmissionForm = document.getElementById('projectForm');

// Add comments for complex logic
// Calculate project completion percentage based on milestones
const completionPercentage = (completedMilestones / totalMilestones) * 100;

Critical Pattern Requirements (from CLAUDE.md):

<!-- ✅ CORRECT: Direct function calls -->
<button onclick="showSection('home')">Home</button>
<button onclick="bulkApproveProjects()">Approve</button>

<!-- ❌ NEVER DO THIS -->
<button onclick="window.capstoneApp.showSection('home')">Home</button>

CSS Guidelines

CSS Organization:

/* Use CSS custom properties */
:root {
    --primary-color: #e31837;
    --secondary-color: #1a1a1a;
    --spacing-md: 1.5rem;
}

/* Follow BEM naming convention */
.project-card {
    /* Component styles */
}

.project-card__title {
    /* Element styles */
}

.project-card--featured {
    /* Modifier styles */
}

/* Mobile-first responsive design */
.container {
    width: 100%;
}

@media (min-width: 768px) {
    .container {
        max-width: 1200px;
    }
}

Database Guidelines

Migration Files:

-- migrations/006_add_feature.sql
-- Always include both up and down migrations
-- Use descriptive naming
-- Include appropriate indexes

CREATE TABLE new_feature (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(255) NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_new_feature_name ON new_feature(name);

API Guidelines

RESTful Endpoints:

// Consistent response format
app.get('/api/projects', (req, res) => {
    res.json({
        success: true,
        data: projects,
        message: 'Projects retrieved successfully'
    });
});

// Error handling
app.use((error, req, res, next) => {
    res.status(error.status || 500).json({
        success: false,
        error: error.message,
        code: error.code || 'INTERNAL_ERROR'
    });
});

🧪 Testing Guidelines

Writing Tests

Unit Tests:

// __tests__/database.test.js
describe('Database', () => {
    test('should create new project', async () => {
        const projectData = {
            title: 'Test Project',
            description: 'Test Description',
            client_id: 1
        };
        
        const project = await database.createProject(projectData);
        expect(project.id).toBeDefined();
        expect(project.title).toBe('Test Project');
    });
});

Integration Tests:

// __tests__/api.test.js
describe('API Endpoints', () => {
    test('POST /api/projects should create project', async () => {
        const response = await request(app)
            .post('/api/projects')
            .set('Authorization', `Bearer ${authToken}`)
            .send(projectData)
            .expect(201);
            
        expect(response.body.success).toBe(true);
        expect(response.body.data.title).toBe(projectData.title);
    });
});

Testing Checklist

Before Submitting:

📚 Documentation Standards

Code Documentation

Function Documentation:

/**
 * Creates a new project in the database
 * @param {Object} projectData - Project information
 * @param {string} projectData.title - Project title
 * @param {string} projectData.description - Project description
 * @param {number} projectData.client_id - Client organization ID
 * @returns {Promise<Object>} Created project object
 * @throws {Error} If project creation fails
 */
async function createProject(projectData) {
    // Implementation
}

User Documentation

Documentation Structure:

# Feature Name

Brief description of the feature.

## Purpose
Why this feature exists and what problem it solves.

## How to Use
Step-by-step instructions with examples.

## Examples
Code examples or screenshots.

## Troubleshooting
Common issues and solutions.

🐛 Bug Reporting

Bug Report Template

**Bug Description**
Clear description of the bug

**Steps to Reproduce**
1. Step one
2. Step two
3. Step three

**Expected Behavior**
What should happen

**Actual Behavior**
What actually happens

**Environment**
- OS: [e.g., Windows 10, macOS Big Sur]
- Browser: [e.g., Chrome 95, Firefox 94]
- Node.js version: [e.g., 16.14.0]

**Screenshots**
Add screenshots if applicable

**Additional Context**
Any other relevant information

Critical Bugs

For security vulnerabilities or critical issues:

  1. Do not create public issues
  2. Email directly to security contact
  3. Provide detailed reproduction steps
  4. Allow time for responsible disclosure

🔄 Release Process

Version Numbering

We use semantic versioning (SemVer):

Release Checklist

Before Release:

👥 Community Guidelines

Code of Conduct

We are committed to providing a welcoming and inclusive environment:

Our Standards:

Unacceptable Behavior:

Communication Channels

For Contributors:

Response Times:

🎓 Learning Resources

Getting Familiar with the Tech Stack

JavaScript and Node.js:

Database and SQL:

Web Development:

Understanding the Project

Start Here:

  1. Read the main README.md
  2. Review ARCHITECTURE.md
  3. Check CLAUDE.md for coding guidelines
  4. Explore the codebase structure
  5. Run the application locally

🏆 Recognition

Contributor Recognition

We value all contributions and recognize contributors through:

GitHub Recognition:

Special Recognition:

Types of Contributions We Value

All contributions matter:

📞 Getting Help

For New Contributors

First Steps:

  1. Join our community discussions
  2. Look for “good first issue” labels
  3. Ask questions in pull request comments
  4. Don’t hesitate to ask for help

Mentorship:

Contact Information

Project Maintainers:

Support Channels:

Thank you for contributing to Curtin Capstone Connect! Your contributions help create better opportunities for students and industry partners to collaborate on meaningful capstone projects.

📄 License

By contributing to this project, you agree that your contributions will be licensed under the same MIT License that covers the project. See LICENSE.md for details.