Contributing Guide

First off, thanks for taking the time to contribute to Gitlantis! All types of contributions are encouraged and valued. Please read the relevant sections below before making your contribution.

​

Code of Conduct

This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code. To report unacceptable behavior, reach out at brayo.co.

​

Ways to Contribute

If you don’t have time to contribute code, there are other ways to support the project:

• Star the project on GitHub
• Tweet about it
• Reference Gitlantis in your project’s readme
• Mention the project at local meetups
• Tell your friends and colleagues

​

Asking Questions

Before asking a question:

1. Search existing Issues
2. Search the internet for answers

If you still need help:

1. Open a new issue
2. Provide as much context as possible about what you’re running into

​

Reporting Bugs

​

Before Submitting a Bug Report

• Ensure you’re using the latest version of Gitlantis
• Determine if your bug is really a bug and not a user error
• Check the bug tracker for existing reports
• Search the internet (including Stack Overflow)
• Collect information:
  • Stack trace or error messages
  • OS, platform, and version (Windows, Linux, macOS, x86, ARM)
  • VS Code version
  • Steps to reproduce the issue
  • Can you reproduce it reliably? With older versions?

​

How to Submit a Bug Report

Security Note: Never report security vulnerabilities publicly. Contact the maintainer at brayo.co.

1. Open an issue
2. Explain the expected behavior vs. actual behavior
3. Provide detailed reproduction steps
4. Include the information you collected above

Once filed:

• The team will label the issue
• A team member will try to reproduce it
• Issues marked needs-repro won’t be addressed until reproduced
• Reproducible bugs will be marked help wanted

​

Suggesting Enhancements

​

Before Submitting an Enhancement

• Use the latest version of Gitlantis
• Search existing issues for similar suggestions
• Ensure your idea fits the project’s scope and goals
• Consider if it benefits the majority of users

​

How to Submit an Enhancement

Enhancement suggestions are tracked as GitHub issues.

• Use a clear and descriptive title
• Provide a step-by-step description of the enhancement
• Describe the current behavior and expected behavior
• Include screenshots or GIFs if applicable
• Explain why this would be useful to most users
• Reference similar implementations in other projects

​

Your First Code Contribution

​

Prerequisites

Before you start, set up your local development environment:

​

Finding an Issue

1. Look for issues labeled:
   • good first issue - Great for newcomers
   • help wanted - Contributions welcome
2. Leave a comment to let others know you’re working on it
3. Wait for maintainer approval before starting work

​

Development Workflow

1. Fork the repository
   # Click "Fork" on GitHub, then clone your fork
   git clone https://github.com/YOUR_USERNAME/gitlantis.git
   cd gitlantis
   
2. Create a branch Use descriptive branch names with prefixes:
   • feature/ - For new features
   • bug/ - For bug fixes
   Examples:
   git checkout -b feature/add-night-mode
   git checkout -b bug/fix-minimap-crash
   
3. Make your changes
   • Write clean, readable code
   • Follow the existing code style
   • Add comments where necessary
   • Update documentation if needed
4. Test your changes
   • Run linting: pnpm lint
   • Check formatting: pnpm format
   • Build the extension: pnpm build
   • Test in VS Code Extension Development Host (F5)
5. Commit your changes Use Conventional Commits format:
   git add .
   git commit -m "feat: add night mode toggle"
   
   Commit Types:
   • feat: - New feature
   • fix: - Bug fix
   • docs: - Documentation changes
   • style: - Code style changes (formatting, semicolons, etc.)
   • refactor: - Code refactoring
   • test: - Adding or updating tests
   • chore: - Maintenance tasks
   • perf: - Performance improvements
   Examples:
   feat: add boat speed control slider
   fix: resolve minimap positioning on small screens
   docs: update setup instructions for Windows
   refactor: simplify node collision detection
   chore: update dependencies
   
6. Push your branch
   git push origin feature/add-night-mode
   
7. Open a Pull Request
   • Go to the Gitlantis repository
   • Click “Compare & pull request”
   • Target the main branch
   • Fill out the PR template:
     • Brief description of changes
     • Related issue number (if applicable)
     • Screenshots/GIFs (if UI changes)
     • Testing steps

​

Code Standards

​

TypeScript

• Use TypeScript for all new code
• Define proper types (avoid any)
• Use interfaces for object shapes
• Prefer const over let

​

React

• Use functional components with hooks
• Keep components small and focused
• Extract reusable logic into custom hooks
• Use proper TypeScript types for props

​

Styling

• Use Tailwind CSS utility classes
• Follow existing naming conventions
• Keep styles consistent with the theme

​

File Organization

• One component per file
• Use index files for barrel exports
• Group related files in folders
• Follow the existing directory structure

​

Comments

• Write self-documenting code when possible
• Add comments for complex logic
• Use JSDoc for public APIs
• Explain “why”, not “what”

​

Pull Request Process

1. Automated Checks Your PR must pass:
   • ESLint validation
   • Prettier formatting
   • Build without errors
2. Review Process
   • A maintainer will review your code
   • Address any requested changes
   • Keep the discussion professional and constructive
3. Merging
   • PRs are merged by maintainers
   • Your branch will be deleted after merging
   • Your contribution will be credited in the release notes

​

Git Hooks

The project uses Husky for automated checks:

​

Pre-commit

• Runs ESLint on staged files
• Runs Prettier on staged files
• Auto-fixes issues when possible
• Blocks commit if errors remain

​

Commit Message

• Validates commit message format
• Ensures conventional commits
• Blocks commits with invalid messages

​

Legal Notice

When contributing to this project, you must agree that:

• You have authored 100% of the content
• You have the necessary rights to the content
• Your content may be provided under the project license

​

Getting Help

If you need help with your contribution:

1. Check the documentation
2. Review the architecture guide
3. Ask in your pull request or issue
4. Reach out to the maintainer at brayo.co

​

Recognition

All contributors will be:

• Listed in the project’s contributors
• Mentioned in release notes
• Credited in the README (for significant contributions)

Thank you for contributing to Gitlantis!