Skip to content

Latest commit

 

History

History
220 lines (152 loc) · 7.28 KB

CONTRIBUTING.md

File metadata and controls

220 lines (152 loc) · 7.28 KB

Contributing to the Makeability Lab Website

This document outlines how to set up your local development environment and our process for submitting changes.

Table of Contents

Prerequisites

Docker Installation

MacOS

  1. Install Docker: Download and install Docker Desktop. Run docker version in your terminal to verify it is running.
  2. Clone the Repository: 
    git clone https://github.com/jonfroehlich/makeabilitylabwebsite.git
cd makeabilitylabwebsite
  3. Build the Image: 
    docker build . -t makelab_image
    Note: This may take 2-3 minutes.
  4. Run the Container: 
    docker-compose -f docker-compose-local-dev.yml up
    To run in detached mode (background), add the -d flag: docker-compose -f docker-compose-local-dev.yml up -d.
  5. Don't forget to create a local superuser to create content (see below).

Windows (WSL2)

If you dev on Windows, you should use WSL2 for better performance and Linux kernel compatibility.

  1. Install WSL2

  2. Install Docker:

    • Install Docker Desktop for Windows.
    • Enable "Use the WSL 2 based engine" in Docker Settings > General.
    • Under Resources > WSL Integration, enable integration for your Linux distro (e.g., Ubuntu).

  3. Clone the Repository (Inside WSL): Open your Linux shell and run:

    git clone https://github.com/makeabilitylab/makeabilitylabwebsite.git
cd makeabilitylabwebsite

  4. Set Permissions: Run the following to ensure Docker can execute scripts and write to folders:

    chmod 755 docker-entrypoint.sh
chmod 777 media
mkdir -p static && chmod -R 777 static/
mkdir -p website/migrations && chmod -R 777 website/

  5. Build and Run:

    docker build . -t makelab_image
docker-compose -f docker-compose-local-dev.yml up

  6. (Optional) Map WSL filesystem to Windows

    Press Win + R, type \\wsl$, find your Linux distro folder, right-click → Map Network Drive. This lets you browse Linux files from Windows Explorer.

  7. Don't forget to create a local superuser to create content (see below).

Running the Website

After initial setup, start the development server with:

docker-compose -f docker-compose-local-dev.yml up

Or use the convenience script:

./run-docker-local-dev.sh

The site will be available at http://localhost:8571.

Note: You don't need to rebuild the image unless you modify Dockerfile or docker-compose.yml. Code changes are reflected automatically.

Shutting Down

To stop the containers:

docker-compose down

Important: Without this command, containers persist in the background even after closing your terminal, keeping port 8571 occupied.

Creating a Superuser

A superuser account is required to access the Django admin interface and add content.

  1. With containers running, open a new terminal

  2. Access the website container:

    docker exec -it makeabilitylabwebsite_website_1 bash

    Note: Depending on your Docker/Compose version, the container name may use a hyphen instead of underscore: makeabilitylabwebsite-website-1

  3. Create the superuser:

    python manage.py createsuperuser

  4. Follow the prompts to set username, email, and password

  5. Exit the container:

    exit

Adding Content

  1. Navigate to the Django admin interface: http://localhost:8571/admin

  2. Log in with your superuser credentials

  3. Under the WEBSITE header, select the content type you want to add (Publications, People, Projects, etc.)

  4. Click ADD in the upper right corner

  5. Fill in the required fields and save

Tip: Only add content needed for the issue you're working on—this saves time during development.

Development Workflow

  1. Find or create an issue

    Browse existing issues or create a new one. Assign yourself to the issue you'll work on.

  2. Create a feature branch

    Branch names should be descriptive and reference the issue:

    git checkout -b 335-adding-hover-to-landing-page  # for issue #335

    Each branch should address a single issue.

  3. Make your changes

    Write code, test locally, and commit with clear messages.

  4. Submit a pull request

    Push your branch and open a PR against master. PRs undergo code review and local testing before merging.

Accessibility Testing

We use Pa11y CI with the Axe engine to run automated accessibility checks against the local site. Tests are configured in .pa11yci.json and target WCAG 2.0 AA compliance.

Running Accessibility Checks

Make sure the website is running first, then run the a11y service:

# Start the website (if not already running)
docker-compose -f docker-compose-local-dev.yml up -d

# Run accessibility checks
docker-compose -f docker-compose-local-dev.yml --profile testing run --rm a11y

To generate a JSON report:

docker-compose -f docker-compose-local-dev.yml --profile testing run --rm a11y sh -c "
  npm install -g pa11y-ci &&
  pa11y-ci --config /workspace/.pa11yci.json --json | tee /workspace/a11y-report.json
"

Configuring Tests

Edit .pa11yci.json to add or remove URLs to test. The urls array lists every page that will be checked.

Pull Request Guidelines

  • UI changes require mockups: Include before/after screenshots or design mockups so we can collectively agree on the visual direction. See issue #287 for a good example.

  • One issue per branch: Keep PRs focused on a single issue for easier review.

  • Test locally: Verify your changes work before submitting.

  • Run accessibility checks: Run the a11y service before submitting UI changes to catch WCAG violations early.

  • Clear descriptions: Explain what changed and why in your PR description.

Troubleshooting

See our Troubleshooting Wiki for common issues and solutions.