Skip to main content
We welcome contributions to Campus! This guide will help you get started with contributing to the project.

​
Getting Started

Campus is an academic social network prototype that connects students, educators, researchers, and administrators. The project is built with modern web technologies and welcomes contributions from the community.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Bun - JavaScript runtime
  • PocketBase - Backend-as-a-Service
  • Git for version control

​
Development Setup

1

Fork and Clone the Repository

Fork the repository on GitHub, then clone your fork:
git clone https://github.com/YOUR_USERNAME/campus.git
cd campus
Add the upstream repository as a remote:
git remote add upstream https://github.com/mgpcampos/campus.git
2

Install Dependencies

Use Bun to install project dependencies:
bun install
3

Configure PocketBase Backend

Download the PocketBase executable for your operating system from pocketbase.io/docs and place it in the project root.Run migrations and start the PocketBase server:
./pocketbase migrate
./pocketbase serve
PocketBase will automatically apply migrations from the pb_migrations folder, creating the necessary database structure.
4

Start the Development Server

In a new terminal window, start the frontend development server:
bun run dev
The application will be accessible at http://localhost:5173. Both frontend and backend must be running simultaneously.

​
Technology Stack

Familiarize yourself with the technologies used in Campus:
CategoryTechnologyDescription
FrontendSvelte 5 + SvelteKitReactive framework for fast web interfaces
StylingTailwind CSS v4Utility-first CSS framework
Backend/DatabasePocketBaseOpen-source Backend-as-a-Service (SQLite-based)
RuntimeBunJavaScript runtime
ComponentsBits UI + LucideHeadless UI components and vector icons
ValidationZod + SuperformsSchema validation and form management

​
Project Structure

.
├── src/
│   ├── lib/            # Reusable components, utilities, and stores
│   ├── routes/         # Application routes (SvelteKit file-based routing)
│   └── app.html        # Main HTML template
├── pb_migrations/      # PocketBase database migrations (JS)
├── pb_hooks/           # PocketBase server-side hooks
├── static/             # Public static files
└── package.json        # Project dependencies and scripts

​
Contribution Workflow

1

Create a Feature Branch

Before making changes, create a new branch from main:
git checkout main
git pull upstream main
git checkout -b feature/your-feature-name
Use descriptive branch names:
  • feature/add-notification-system
  • fix/profile-image-upload
  • docs/update-api-documentation
2

Make Your Changes

Write clean, maintainable code that follows the project’s existing patterns:
  • Follow the existing code style and conventions
  • Write meaningful commit messages
  • Keep commits focused and atomic
  • Test your changes thoroughly
3

Test Your Changes

Ensure your changes work correctly:
  • Test all affected features manually
  • Verify both frontend and backend functionality
  • Check responsive design on different screen sizes
  • Test in both light and dark mode if UI changes are involved
4

Commit Your Changes

Write clear, descriptive commit messages:
git add .
git commit -m "feat: add user notification preferences"
Use conventional commit prefixes:
  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • style: - Code style changes (formatting)
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Maintenance tasks
5

Push to Your Fork

Push your changes to your GitHub fork:
git push origin feature/your-feature-name
6

Open a Pull Request

Go to the original Campus repository on GitHub and open a pull request:
  • Provide a clear title describing the change
  • Include a detailed description of what changed and why
  • Reference any related issues (e.g., “Closes #123”)
  • Add screenshots for UI changes
  • Ensure all checks pass

​
Pull Request Guidelines

​
Before Submitting

  • Ensure your code follows the project’s style and conventions
  • Update documentation if you’re changing functionality
  • Keep pull requests focused on a single feature or fix
  • Rebase on the latest main branch to avoid merge conflicts

​
PR Description Template

Provide a comprehensive description: 
## Description
Brief description of what this PR does

## Changes
- List of specific changes made
- Another change

## Screenshots (if applicable)
[Add screenshots for UI changes]

## Related Issues
Closes #123

## Testing
How to test these changes

​
Review Process

  • Be responsive to feedback and questions
  • Be open to suggestions and constructive criticism
  • Make requested changes promptly
  • Keep discussions professional and focused

​
Reporting Issues

If you find a bug or have a feature request:
  1. Check if the issue already exists in the GitHub issues
  2. If not, create a new issue with a clear title and description
  3. Include steps to reproduce for bugs
  4. Add screenshots or error messages if applicable
  5. Tag the issue appropriately (bug, enhancement, question, etc.)

​
Questions?

If you have questions about contributing:
  • Open a GitHub Discussion
  • Check existing issues and pull requests
  • Review the project documentation
Thank you for contributing to Campus!

Build docs developers (and LLMs) love

Get started for freeTalk to us