UoMMods

Contribute to UoMMods

UoMMods is an open-source course management system built by University of Manchester students, for students. Join our community to help improve course planning and academic optimization for everyone.

View RepositoryBrowse IssuesJoin Discussions
Prerequisites & Development Setup

System Requirements

  • Node.js v18+ (LTS recommended)
  • npm v9+ (comes with Node.js)
  • Python v3.8+ (for data scraping)
  • Git for version control
  • Code editor (VS Code recommended)

Technical Knowledge

  • TypeScript/JavaScript (React patterns)
  • Next.js 15 (App Router)
  • Tailwind CSS (utility-first styling)
  • Python (for scraping scripts)
  • Git workflows (branching, PRs)

Setup Instructions

  1. Clone the repository:
    git clone https://github.com/b1-ing/uommods
cd uommods
  2. Set up Python environment (for scraping scripts):
    python -m venv .venv
.venv\Scripts\activate     # Windows
source .venv/bin/activate  # Unix/macOS
pip install -r requirements.txt
  3. Set up Next.js application:
    cd uommods
npm install
  4. Configure environment variables:
    cp .env.template .env.local
openssl rand -base64 60  # Generate SESSION_PASSWORD

    Update .env.local with the generated session password and any other required values.

  5. Start development server:
    npm run dev

    Visit http://localhost:3000 to see the application running locally.

How You Can Contribute

Frontend Development

Frontend Issues
  • Improve React components with TypeScript
  • Enhance UI/UX using Tailwind CSS and Radix UI
  • Add interactive features and visualizations
  • Optimize performance and accessibility
  • Fix bugs and improve code quality
Skills: React, TypeScript, Tailwind CSS, Next.js

Data & Backend

Backend Issues
  • Improve Python web scraping scripts
  • Optimize Supabase database queries
  • Add new data sources and processing
  • Enhance API endpoints and data sync
  • Work on authentication and session management
Skills: Python, PostgreSQL, Supabase, Web Scraping

University Data

Data Issues
  • Update course information and prerequisites
  • Improve grade distribution accuracy
  • Add new academic year data
  • Enhance module search and filtering
  • Validate scraped data accuracy
Skills: Data Analysis, University Systems, Python

Documentation & Testing

Documentation Issues
  • Improve developer documentation
  • Write user guides and tutorials
  • Add unit and integration tests
  • Create example workflows
  • Document API endpoints
Skills: Technical Writing, Testing Frameworks
Coding Standards & Best Practices

TypeScript/React Standards

  • ✅ Use strict TypeScript - avoid any types
  • ✅ Prefer functional components with React hooks
  • ✅ Use proper prop typing with interfaces
  • ✅ Follow React patterns - useState, useEffect, custom hooks
  • ✅ Keep components small and focused
  • ✅ Use Radix UI components for consistency

Styling & UI Guidelines

  • ✅ Use Tailwind CSS utility classes
  • ✅ Follow mobile-first responsive design
  • ✅ Ensure accessibility (ARIA labels, keyboard nav)
  • ✅ Maintain consistent spacing and typography
  • ✅ Test on multiple screen sizes
  • ✅ Use semantic HTML elements

Python Standards

  • ✅ Follow PEP 8 style guidelines
  • ✅ Use type hints for function parameters
  • ✅ Add docstrings to functions and classes
  • ✅ Handle errors gracefully with try/except
  • ✅ Use virtual environments for dependencies
  • ✅ Validate scraped data before processing

Git & Development

  • ✅ Use conventional commits (feat:, fix:, docs:)
  • ✅ Create descriptive branch names
  • ✅ Run linting before committing
  • ✅ Test locally before pushing
  • ✅ Write clear PR descriptions
  • ✅ Link PRs to relevant issues

Quality Checklist

Before submitting your PR, ensure you've completed these steps:

□ Code builds without errors: npm run build
□ Linting passes: npm run lint
□ No TypeScript errors in IDE
□ Tested on mobile and desktop
□ Accessible with keyboard navigation
□ No console errors or warnings
Contribution Workflow
  1. Find or create an issue:

    Browse existing issues or create a new one. For major changes, discuss in GitHub Discussions first.

  2. Fork and create a branch:
    git checkout -b feat/course-planner-export
# Use prefixes: feat/, fix/, docs/, refactor/
  3. Make changes with clear commits:
    git add .
git commit -m "feat(planner): add CSV export functionality"

# Follow conventional commits format:
# type(scope): description
  4. Test your changes:
    npm run lint    # Check for linting issues
npm run build   # Ensure build succeeds
# Test manually in browser
  5. Push and open a Pull Request:
    git push origin feat/course-planner-export

    Include screenshots/GIFs for UI changes, describe what you tested, and reference the issue with "Fixes #123" to auto-close on merge.

  6. Respond to review feedback:

    Address reviewer comments, make requested changes, and be respectful in discussions. We'll merge once all checks pass!

Security & Privacy Guidelines

⚠️ Important Security Rules

  • • Never commit real student data - use anonymized test data only
  • • Don't expose API keys - use environment variables
  • • Handle authentication securely - follow established patterns
  • • Validate all user inputs - prevent injection attacks
  • • Respect University policies - follow data usage guidelines

Data Privacy

  • • Use synthetic data for development
  • • Anonymize any real course data
  • • Follow GDPR principles
  • • Document data usage clearly

Authentication

  • • Use University of Manchester SSO
  • • Implement proper session management
  • • Validate user permissions
  • • Log security-relevant events
Community & Support

UoMMods is built by University of Manchester students for the benefit of the entire student community. We welcome contributors of all skill levels and backgrounds.

Getting Help

  • • Check existing documentation first
  • • Search closed issues for similar problems
  • • Ask questions in GitHub Discussions
  • • Tag maintainers for urgent issues

Code of Conduct

  • • Be respectful and inclusive
  • • Provide constructive feedback
  • • Help newcomers learn
  • • Follow University community standards
Start a DiscussionStar the Repository ⭐

Ready to contribute to UoMMods?

Whether you're fixing a small bug, adding a new feature, or improving documentation, every contribution helps make course planning better for University of Manchester students.

View Open Issues

Built with ❤️ by University of Manchester students, for students. Thanks for helping make UoMMods better for everyone.