Contributing Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• TODO.md
• README.md
• finder/static/finder/js/scripts.js
• finder/static/finder/css/styles.css
• roomfinder/settings.py
• generate_sample_data.py
• finder/templates/finder/upload_excel.html
• finder/tests.py
• finder/templates/finder/search.html

This document provides guidelines for contributing to the Campuspal Room Finder project. The project is a web application designed to help students and staff find available rooms on campus. We welcome contributions in the form of bug fixes, new features, and documentation improvements. Following these guidelines helps maintain the quality and consistency of the codebase.

Sources: CONTRIBUTING.md:3-4, README.md:3-5

How to Contribute

The project follows a standard fork-and-pull-request workflow on GitHub. Before starting, it's recommended to check for existing issues or create a new one to discuss your proposed changes. Small, focused Pull Requests (PRs) are preferred.

Sources: CONTRIBUTING.md:6, CONTRIBUTING.md:29-30

Contribution Workflow

The following diagram illustrates the end-to-end process for submitting a contribution.

This diagram shows the standard GitHub contribution flow.
Sources: CONTRIBUTING.md:7-26

Step-by-Step Commands

1. Fork and Clone:

   # Clone your forked repository
   git clone https://github.com/YOUR_USERNAME/roomfinder.git
   cd roomfinder
   

   Sources: CONTRIBUTING.md:9-12

2. Create a Branch:

   # Create a new branch for your feature or fix
   git checkout -b feature/your-feature-name
   

   Sources: CONTRIBUTING.md:14-16

3. Commit and Push:

   # After making changes, commit them with a descriptive message
   git commit -m "Add your-feature description"
   
   # Push the branch to your fork on GitHub
   git push origin feature/your-feature-name
   

   Sources: CONTRIBUTING.md:22-26

4. Create a Pull Request:
   Navigate to the original Allen739/roomfinder repository on GitHub and open a new Pull Request from your branch. Provide a clear description of your changes.
   Sources: CONTRIBUTING.md:28-30

Development Environment Setup

To work on the project, you need to set up a local development environment. This involves installing dependencies, setting up the database, and loading sample data.

Sources: README.md:213-242

Setup Flow

This diagram outlines the steps to get the application running locally.
Sources: README.md:213-242

Setup Commands

The following commands guide you through the setup process:

1. Install Dependencies:

   pip install -r requirements.txt
   

   Sources: README.md:221-223

2. Database Setup:

   # Apply database schema changes
   python manage.py makemigrations finder
   python manage.py migrate
   

   Sources: README.md:224-227

3. Load Data:

   # Generate sample .xlsx files in sample_data/
   python generate_sample_data.py
   
   # Clear existing data and load new data
   python manage.py shell -c "from finder.models import Room, ClassSchedule; Room.objects.all().delete(); ClassSchedule.objects.all().delete()"
   python manage.py load_rooms_excel
   python manage.py load_timetable
   

   Sources: README.md:228-237, generate_sample_data.py

4. Run Server:

   python manage.py runserver
   

   Sources: README.md:239-241

Code Quality and Style

Maintaining a consistent code style is crucial. Contributions should adhere to the project's standards for code quality and formatting.

Code Style (PEP 8)

The project uses the PEP 8 style guide for Python code. You can use a linter like flake8 to check your code for compliance.

Sources: CONTRIBUTING.md:29

Linting Issues to Address

The TODO.md file lists several existing flake8 linting issues that are currently ignored in the CI pipeline but should be fixed. Contributions that address these issues are welcome.

Error Code	Description	Example File:Line
E501	Line too long (>120 characters)	finder/views.py:172
F401	Unused import	finder/tests.py:1
E261	At least two spaces before inline comment	roomfinder/settings.py:41
W291	Trailing whitespace	roomfinder/settings.py:41
E303	Too many blank lines	roomfinder/settings.py:84

Sources: TODO.md:3-29

Testing

Adding and updating tests is a critical part of the contribution process, ensuring that new features work as expected and do not introduce regressions.

Sources: CONTRIBUTING.md:18, CONTRIBUTING.md:20

Running Tests

You can run the test suite locally using the following command:

python manage.py test

Ensure that existing tests pass and that new tests are added for any new functionality.

Sources: CONTRIBUTING.md:20-21

Test Coverage

The current test file, finder/tests.py, is a placeholder. A major area for contribution is to add proper tests for the finder application to improve coverage and stability.

# finder/tests.py
# Create your tests here.
# TODO: Add proper tests for the finder application

Sources: finder/tests.py:1-3, TODO.md:12-13

Documentation and Data

If your contribution changes functionality or adds new features, you may need to update the project's documentation or sample data generation scripts.

• Update README.md: If you add or change a major feature, update the README.md file to reflect the changes.
  Sources: CONTRIBUTING.md:19
• Sample Data: The generate_sample_data.py script creates realistic data for testing. If you modify the data model (e.g., in finder/models.py), you may need to update this script to include new fields.
  Sources: generate_sample_data.py, README.md:92-94

Areas for Contribution

The project has several areas where contributions would be particularly valuable.

Feature Enhancements

The README.md outlines several potential future enhancements:

• Natural Language Search
• Predictive Availability
• Room Booking System
• User Accounts & Favorites
• Admin Dashboard

Sources: README.md:246-255

Technical Debt

• Fix Linting Errors: Address the flake8 errors listed in TODO.md.
  Sources: TODO.md:3-29
• Add Unit Tests: Implement a comprehensive test suite in finder/tests.py.
  Sources: finder/tests.py:3
• Improve CI: Configure PostgreSQL in the CI environment for more realistic testing, as the current setup falls back to SQLite.
  Sources: TODO.md:32-34

Thank you for helping make Room Finder better!

Sources: CONTRIBUTING.md:34