Skip to main content
Thank you for considering contributing to gSubs! Your contributions help make gSubs better for everyone. This guide will help you get started with the contribution process.

​
Ways to contribute

There are many ways to contribute to gSubs:

Code contributions

Add features, fix bugs, or improve performance

Documentation

Write tutorials, improve docs, or create guides

Bug reports

Report issues and help identify problems

Feature requests

Suggest new features and improvements

​
Getting started

1

Fork the repository

Fork the gSubs repository to your own GitHub account. This creates your own copy where you can make changes.
# Clone your fork
git clone [email protected]:YOUR_USERNAME/gsubs.git
cd gsubs
2

Set up your development environment

Install dependencies and verify everything works:
npm install
npm start
See the setup guide for detailed instructions.
3

Create a feature branch

Create a new branch for your work:
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description
Use descriptive branch names:
  • feature/add-subtitle-preview
  • fix/drag-drop-validation
  • docs/update-readme
4

Make your changes

Write your code, following the guidelines below. Make sure to:
  • Test your changes thoroughly
  • Follow the existing code style
  • Add comments for complex logic
  • Update documentation if needed
5

Commit your changes

Write clear, descriptive commit messages:
git add .
git commit -m "Add subtitle preview feature"
Use present tense (“Add feature” not “Added feature”) and be specific about what changed.
6

Push and create a pull request

Push your changes to your fork:
git push origin feature/your-feature-name
Then create a pull request on GitHub from your fork to the main repository.

​
Contribution guidelines

​
Code style

Follow the existing code style in the project:
  • Indentation: Use consistent indentation (the project uses spaces)
  • Naming: Use descriptive variable and function names
  • Comments: Add comments for complex logic or non-obvious behavior
  • jQuery: Follow jQuery conventions for DOM manipulation
// Good: Descriptive function name and clear logic
function validateVideoFileExtension(fileName) {
    var extensionLists = ['m4v', 'avi', 'mpg', 'mp4', 'webm', 'mkv'];
    return extensionLists.indexOf(fileName.split('.').pop()) > -1;
}

​
Testing your changes

Before submitting a pull request:
  • Drag and drop: Try single and multiple files
  • Search: Test with various movie/series names
  • Language selection: Switch between different languages
  • Download: Verify subtitles download correctly
  • Invalid file types
  • Network errors
  • No search results
  • Multiple subtitle matches
  • Empty search queries
Test the app on your operating system:
  • Windows: Run npm run dist:win
  • macOS: Run npm run dist:mac
  • Linux: Run npm run dist:linux

​
Commit message format

Write clear commit messages that explain what and why: 
Add subtitle preview before download

Implemented a modal that shows subtitle content preview before
downloading. This helps users verify they're getting the correct
subtitle file.

​
Pull request guidelines

When creating a pull request:
  1. Title: Use a clear, descriptive title
  2. Description: Explain what changes you made and why
  3. Screenshots: Include screenshots for UI changes
  4. Testing: Describe how you tested your changes
  5. Breaking changes: Note any breaking changes
Your pull request will be reviewed by maintainers. Be patient and responsive to feedback.

​
Types of contributions

​
Adding features

When adding new features:
  1. Discuss first: Open an issue to discuss the feature before implementing
  2. Keep it simple: Follow the existing UI/UX patterns
  3. Update docs: Add documentation for new features
  4. Test thoroughly: Ensure the feature works across platforms

​
Fixing bugs

When fixing bugs:
  1. Reference the issue: Link to the GitHub issue in your PR
  2. Explain the fix: Describe what caused the bug and how you fixed it
  3. Add prevention: Consider how to prevent similar bugs in the future
  4. Test the fix: Verify the bug is actually fixed

​
Improving documentation

Documentation improvements are always welcome:
  • Fix typos and grammar
  • Add code examples
  • Clarify confusing sections
  • Add troubleshooting tips
  • Create tutorials

​
Adding subtitle sources

To add a new subtitle source:
  1. Find a subtitle API with good coverage
  2. Add the npm package to dependencies
  3. Implement the search logic in app/renderer/checksub.js
  4. Update the search order in app/renderer/index.js
  5. Test with various video files
Current sources:
  • SubDB (hash-based matching)
  • OpenSubtitles (search and metadata)
Planned sources:
  • Addic7ed (TV shows)

​
Code review process

After submitting a pull request:
  1. Automated checks: Wait for any automated checks to complete
  2. Maintainer review: A maintainer will review your code
  3. Feedback: Address any requested changes
  4. Approval: Once approved, your PR will be merged
  5. Recognition: Your contribution will be credited
Contributors are recognized on the gSubs Contributors page.

​
Community guidelines

Please be respectful and constructive:
  • Be respectful: Treat everyone with respect
  • Be patient: Maintainers are volunteers
  • Be constructive: Provide helpful feedback
  • Be collaborative: Work together to improve gSubs

​
Getting help

If you need help:
  1. Check the docs: Read the setup guide and architecture guide
  2. Search issues: Look for similar issues on GitHub
  3. Ask questions: Open a GitHub issue with your question
  4. Be specific: Provide details about your environment and the problem

​
License

By contributing to gSubs, you agree that your contributions will be licensed under the MIT License. All contributions are copyright © Cholaware.

​
Financial contributions

If you’d like to support gSubs financially:
  • PayPal: paypal.me/sanjevirau
  • Use case: Donations help fund development and releases for macOS and Linux

​
Next steps

Ready to contribute?

Setup guide

Get your development environment ready

Architecture

Learn how gSubs works internally

Building

Build gSubs for distribution

GitHub issues

Find issues to work on
Thank you for contributing to gSubs! Every contribution, no matter how small, helps make gSubs better for everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us