Skip to content

Contributing

This documentation site

This site is built with Zensical. To propose changes to these docs:

  1. Clone the repository that hosts this documentation.
  2. Edit Markdown under docs/.
  3. Run zensical serve locally to preview (see the repository README).
  4. Open a pull request.

If the documentation repository is separate from BetterSEQTA+, mention both when a change spans extension behaviour and documentation.

BetterSEQTA+ extension

The extension is open source under the MIT License. Use the sections below: repository guidelines (quick norms), getting started (first-time setup), then extended guidelines (code of conduct, branches, reviews).

Useful pages on this site: Install (including development setup), Architecture, Plugin development, Troubleshooting. Community: Discord.

Repository guidelines

Short norms from the main repository. For your first setup, skip to Getting started as a contributor below.

Never contributed to an open source project before? You can:

We have lots of good first issue labels that are perfect for beginners!

Discussion Before Contributing

For significant changes, please first discuss what you'd like to change via: - Opening an issue - Joining our Discord server - Emailing the maintainers

This helps ensure your contribution aligns with the project's goals and saves you time!

Community

Join our community channels to discuss the project, get help, and connect with other contributors:

  • Discord Server: Join our Discord
  • GitHub Discussions: For longer-form conversations
  • GitHub Issues: For bug reports and feature requests

Creating Plugins

If you're interested in creating plugins for BetterSEQTA+, check out our plugin development guides:

Pull Request Process

  1. It is recommended to start by opening an issue to discuss the change you wish to make. This will allow us to discuss the change and ensure it is a good fit for the project.
  2. Fork the repo and create your branch from main.
  3. When writing your pull request, make sure to use the pull request template.

Pull Request Template

## Description

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.

Fixes # (issue)

## Type of change

Please delete options that are not relevant.

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

Issues

Create a new issue

If you spot a problem with the readme or code, search if an issue already exists. If a related issue doesn't exist, you can open a new issue using a relevant issue form.

Solve an issue

Scan through our existing issues to find one that interests you. You can narrow down the search using labels as filters. As a general rule, we don’t assign issues to anyone. If you find an issue to work on, you are welcome to open a PR with a fix.

Getting started as a contributor

Welcome to BetterSEQTA+! This guide will walk you through making your first contribution, even if you're completely new to the project.

Table of Contents

Before You Start

What You'll Need

  • Node.js (v16 or higher) - Download here
  • Git - Download here
  • A code editor - We recommend VS Code
  • A Chromium browser (Chrome, Edge, Brave) for testing (recommended, however you can use firefox although it requires being built every time you make a change)

Helpful Background (but not required!)

  • Basic JavaScript/TypeScript knowledge
  • Some familiarity with HTML/CSS
  • Understanding of browser extensions (we'll teach you!)

Don't worry if you're missing some of these! We're happy to help you learn. 🤗

Your First 30 Minutes

Let's get you up and running quickly:

1. Get the Code (3 minutes)

# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/BetterSEQTA-Plus.git
cd BetterSEQTA-Plus

2. Install Dependencies (3 minutes)

npm install --legacy-peer-deps

3. Start Development Server (2 minutes)

npm run dev

4. Load Extension in Browser (4 minutes)

  1. Open Chrome and go to chrome://extensions
  2. Enable "Developer mode" (toggle in top right)
  3. Click "Load unpacked"
  4. Select the dist folder in your project
  5. Visit a SEQTA Learn page to see BetterSEQTA+ in action!

5. Make a Tiny Change (5 minutes)

Let's prove everything works: 1. Open src/SEQTA.ts 2. Find the line that says "[BetterSEQTA+] Successfully initialised" 3. Change it to "[BetterSEQTA+] Successfully initialised - Hello [YOUR_NAME]!" 4. Save the file 5. Go to chrome://extensions, click the refresh icon on BetterSEQTA+ 6. Refresh a SEQTA page and check the browser console (F12) - you should see your message!

6. Reset Your Change (3 minutes)

git checkout -- src/SEQTA.ts

Congratulations! 🎉 You've successfully set up BetterSEQTA+ for development!

Making Your First Contribution

Easy First Contributions

Here are some great starter contributions:

  1. Fix a typo in documentation - Super easy and always appreciated!
  2. Improve error messages - Make them more helpful
  3. Add comments to code - Help other contributors understand
  4. Create a simple plugin - Follow our plugin guide
  5. Fix a bug you found - If you found a bug, fix it!

Step-by-Step: Your First Pull Request

Step 1: Pick an Issue

  • Go to our Issues page
  • Look for labels like:
  • good first issue - Perfect for beginners
  • help wanted - We'd love help with these
  • documentation - Improve our docs
  • bug - Fix something broken

Step 2: Claim the Issue

Comment on the issue saying "I'd like to work on this!" We'll assign it to you.

Step 3: Create a Branch

git checkout -b fix-issue-123  # Replace 123 with the issue number

Step 4: Make Your Changes

  • Follow the patterns you see in existing code
  • Test your changes thoroughly
  • Keep changes focused and small

Step 5: Test Everything

# Test the extension still loads
npm run dev

# Test in browser
# 1. Reload extension at chrome://extensions
# 2. Visit SEQTA page
# 3. Verify everything still works

Step 6: Commit Your Changes

git add .
git commit -m "Fix issue #123: Brief description of what you fixed"

Step 7: Push and Create Pull Request

git push origin fix-issue-123

Then go to GitHub and create a pull request with: - Clear title: "Fix issue #123: Brief description" - Description: Explain what you changed and why - Testing: Describe how you tested it

Types of Contributions

🐛 Bug Fixes

  • Fix broken features
  • Improve error handling
  • Resolve compatibility issues

Example: "The theme selector doesn't work on Firefox"

✨ New Features

  • Add new plugins
  • Enhance existing functionality
  • Improve user experience

Example: "Add keyboard shortcuts for common actions"

📚 Documentation

  • Fix typos and unclear explanations
  • Add examples and tutorials
  • Improve code comments

Example: "Add more examples to the plugin guide"

🎨 Design & UI

  • Improve the settings interface
  • Make things more user-friendly
  • Add animations and polish

Example: "Make the theme creator more intuitive"

🔧 Technical Improvements

  • Refactor code for clarity
  • Add tests
  • Improve performance

Example: "Simplify the plugin loading logic"

Finding Something to Work On

Browse Issues by Label

Create Your Own Issue

Found a bug or have an idea? Create an issue first to discuss it!

Plugin Ideas

Want to create a plugin? Here are some ideas: - Study Timer: Track study time across SEQTA pages - Grade Tracker: Better visualization of grades over time - Quick Notes: Add notes to any SEQTA page - Homework Reminder: Smart notifications for upcoming due dates - Custom Shortcuts: User-defined keyboard shortcuts

Development Workflow

Daily Development

# Start working
git pull origin main
npm run dev

# Make changes, test, commit
git add .
git commit -m "Descriptive commit message"

# Push when ready
git push origin your-branch-name

Before Submitting PR

  1. Test thoroughly - Make sure nothing breaks
  2. Check console - No new errors
  3. Test in different browsers - Chrome and Firefox
  4. Update documentation - If you changed how something works

Code Style

  • Use TypeScript where possible
  • Follow existing naming conventions
  • Add comments for complex logic
  • Keep functions small and focused

Getting Help

Stuck? Here's How to Get Unstuck

  1. Check the docs - Architecture guide explains everything
  2. Search existing issues - Someone might have had the same problem
  3. Ask in Discord - Our community is super helpful
  4. Create an issue - If you found a bug or need help

Discord Community

Join our Discord server for: - Real-time help and discussion - Collaboration on features - Sharing ideas and feedback - Getting to know the community

Code Review Process

  • All contributions need code review
  • We'll provide helpful feedback
  • Don't worry about making mistakes - we're here to help!
  • Reviews usually happen within 24-48 hours

Common Questions

Q: I'm new to browser extensions. Is this too advanced for me? A: Not at all! We have lots of beginner-friendly issues, and our plugin system makes it easy to add features without understanding all the browser extension complexities.

Q: How long does it take to get my first PR merged? A: For simple fixes, usually 1-3 days. For larger features, it might take a week or two as we discuss the best approach.

Q: I made a mistake in my PR. What do I do? A: No worries! Just push more commits to the same branch and they'll be added to your PR automatically.

Q: Can I work on multiple issues at once? A: It's better to focus on one issue at a time, especially when starting out. This makes code review easier and reduces conflicts.

Q: What if I start working on something and get stuck? A: Ask for help! Create a draft PR with what you have so far, and we'll help you figure out the next steps.

Recognition

All contributors get: - Recognition in our README - Contributor badge in Discord - Our eternal gratitude! 🙏

Significant contributors may also get: - Special Discord roles - Input on project direction - Maintainer status

Next Steps

Ready to contribute? Here's what to do:

  1. ✅ Set up your development environment (follow the 30-minute guide above)
  2. 🔍 Find an issue to work on (check the "good first issue" label)
  3. 💬 Join our Discord and introduce yourself
  4. 🚀 Make your first contribution and submit a PR

Remember: Every expert was once a beginner! We're excited to help you learn and grow as a contributor. Welcome to the team! 🎉

Questions? Suggestions for improving this guide? Open an issue or message us on Discord!

Extended contributing guidelines

The following sections provide detailed policies (code of conduct, branching, reviews, and more).

Table of Contents (extended)

Code of Conduct

BetterSEQTA+ is committed to providing a welcoming and inclusive environment for all contributors. We expect all participants to adhere to our Code of Conduct, which promotes respectful and harassment-free interaction.

Key points:

  • Be respectful and inclusive
  • Focus on what is best for the community
  • Show empathy towards other community members
  • Be open to constructive feedback

Getting Started

Setting Up Your Development Environment

  1. Fork the Repository

Start by forking the BetterSEQTA+ repository to your GitHub account.

  1. Clone Your Fork
git clone https://github.com/yourusername/BetterSEQTA-Plus.git
cd BetterSEQTA-Plus
  1. Install Dependencies
npm install
  1. Set Up Development Environment
npm run dev
  1. Install in Chrome/Firefox

Follow Install to load the development version into your browser.

Project Structure

Understanding the project structure will help you navigate the codebase:

betterseqta-plus/
├── src/                  # Source code
│   ├── plugins/          # Plugin system
│   │   ├── built-in/     # Built-in plugins
│   │   ├── core/         # Plugin core functionality
│   ├── settings/         # Settings system
│   ├── utils/            # Utility functions
│   ├── extension/        # Browser extension code
├── docs/                 # Documentation
├── test/                 # Test files
├── dist/                 # Build output (generated)
├── package.json          # Project dependencies
├── tsconfig.json         # TypeScript configuration
└── README.md             # Project README

Contributing Code

Branching Strategy

We follow a simple branching strategy:

  • main - The main development branch
  • feature/* - Feature branches
  • bugfix/* - Bug fix branches
  • docs/* - Documentation branches

Always create a new branch for your changes:

git checkout -b feature/my-new-feature

Pull Request Process

  1. Keep PRs Focused

Each pull request should address a single concern. If you're working on multiple features, create separate PRs for each.

  1. Write Clear Commit Messages

Follow the conventional commits format:

feat: add new feature
fix: resolve bug with timetable
docs: update installation instructions
  1. Update Documentation

If your changes require documentation updates, include them in the same PR.

  1. Run Tests

Make sure all tests pass before submitting your PR:

npm test
  1. Submit Your PR

When you're ready, push your branch and create a pull request on GitHub.

  1. Code Review

All PRs will be reviewed by maintainers. Be responsive to feedback and make requested changes.

  1. Merge

Once approved, a maintainer will merge your PR.

Coding Standards

We follow TypeScript best practices and have a consistent code style:

  1. Use TypeScript

All new code should be written in TypeScript with proper typing.

  1. Follow Existing Patterns

Match the coding style of the existing codebase.

  1. Write Tests

Add tests for new features and bug fixes.

  1. Document Your Code

Add comments for complex logic and JSDoc comments for functions.

  1. Use Linters

We use ESLint and Prettier. Run them before submitting your PR:

npm run lint
npm run format

Reporting Bugs

If you find a bug, please report it by creating an issue on GitHub:

  1. Search Existing Issues

Check if the bug has already been reported.

  1. Use the Bug Report Template

Fill in all sections of the bug report template:

  • Description
  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Screenshots (if applicable)

  • Environment (browser, OS, etc.)

  • Be Specific

The more details you provide, the easier it will be to fix the bug.

Suggesting Features

We welcome feature suggestions! To suggest a new feature:

  1. Search Existing Suggestions

Check if your idea has already been suggested.

  1. Use the Feature Request Template

Fill in all sections of the feature request template:

  • Description
  • Use case
  • Potential implementation

  • Alternatives considered

  • Be Patient

Feature requests are evaluated based on alignment with project goals, feasibility, and maintainer bandwidth.

Writing Documentation

Good documentation is crucial for the project. To contribute to documentation:

  1. Identify Gaps

Look for areas where documentation is missing or unclear.

  1. Follow Documentation Style

Maintain a consistent style and format.

  1. Use Clear Language

Write in simple, clear English. Avoid jargon when possible.

  1. Include Examples

Code examples and screenshots help users understand.

  1. Submit a PR

Follow the same process as code contributions, but create a branch with a docs/ prefix.

Community

Join our community channels to discuss the project, get help, and connect with other contributors:

  • Discord Server: Join our Discord
  • GitHub Discussions: For longer-form conversations
  • GitHub Issues: For bug reports and feature requests

Creating Plugins

If you're interested in creating plugins for BetterSEQTA+, check out our plugin development guides:

Recognition

Contributors are recognized in several ways:

  1. CONTRIBUTORS.md: All contributors are listed in this file
  2. Release Notes: Significant contributions are highlighted in release notes
  3. Community Recognition: Regular shout-outs in community channels

Questions?

If you have any questions about contributing, please:

  1. Check the documentation
  2. Ask in the Discord server
  3. Open a GitHub Discussion

Thank you for contributing to BetterSEQTA+! Your efforts help make SEQTA better for students and teachers everywhere.