Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
249 lines (187 loc) · 10.5 KB

CONTRIBUTING.md

File metadata and controls

249 lines (187 loc) · 10.5 KB
Raw

Contributing to PyCeas

Thank you for taking the time to contribute! All types of contributions are encouraged and valued. This project started from a passion for Sea of Thieves, inspired by its seafearing spirit.

If you like the project, but just don't have time to contribute, that's fine. You could help us out to show support and appreciation of the project by:

  • 🌟 Starring the project
  • 🗣️ Sharing it on social media or at meetups.
  • 📄 Mention the project in your own repositories or documentation.

Table of Contents

Code of Conduct

Please note we have a code of conduct, please follow it in all your interactions with the project. Go to code of conduct

I Want To Contribute

Legal Notice

When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license. Tip: If you use assets with a creative commons license you can use it without any legal issues. We keep a list of all the assets, software etc in this file.

How We Handle Issues

We use specific templates to ensure issues and tasks are well-structured and easy to collaborate on.

User Story-Based Issues

We use user stories to break down complex features into manageable tasks. Each issue can include multiple user stories, which may be converted into separate issues for collaboration.

  • What is a User Story? A user story describes the functionality from the user's perspective.
    Example:

    As a player, I want to see seamless transitions between the main menu and the game map so that my experience feels smooth and uninterrupted.

  • How Do We Use User Stories? Each user story includes:

    • A clear description of the user's goal.
    • A list of tasks required to implement the story.
    • Guidance for contributors (e.g., file references, related issues).

Check out our User Story-Based Template for detailed guidance.

Reporting Bugs

Steps for a Good Bug Report

  1. Check if you are using the latest version of PyCeas.
  2. Gather the following information:
    • OS, Python version, and project version.
    • Steps to reproduce the bug.
    • Any error messages or screenshots.
  3. Submit the bug using our Bug Report Template

Visual Proof

For bugs that are hard to explain, a short GIF or video is incredibly helpful. We recommend using:

  • LICEcap: A free tool for Windows and macOS to create GIFs of your screen.
  • Peek: A Linux-friendly alternative.

Please attach the GIF or video to your bug report!

IMPORTANT: Do not report security vulnerabilities here.
Please email sensitive issues to PySeasproject@proton.me. We use ProtonMail, a secure, privacy-focues email provider, to handle all security communications. Your messages are encryped in transit for added privacy. The email may still be seen as PySeas, this is not misspelled, this was made before we changed our project's name, will change in the future!

Suggesting Enhancements

We welcome your ideas to improve PyCeas! Whether it's a completely new feature or minor improvement, your contributions help shape the project. Follow these steps to submit an enhancement suggestion:

Ready to propose an enhancement? Use the Enhancement Template

Before Submitting an Enhancement

Steps for a Good Enhancement Suggestion

  1. Check the Documentation to ensure the feature doesn't already exist.
  2. Search for similar suggestions in Issues.

Enhancement suggestions should include:

  • A clear and descriptive title.
  • A step-by-step description of the proposed feature or improvement.
  • An explanation of why this enhancement is useful.
  • Screenshots or GIFs if applicable (see the Visual Proof section for tools).

Proposing Ideas or Tasks (Contributor Guide)

If you're new or have an idea for the project, use our Contributor Guide Template to structure your proposal.

This template helps you:

  • Describe your idea or task.
  • Get feedback from maintainers.
  • Understand next steps to get started.

Example: If you're proposing a feature for the map, you can describe how it improves the player experience and outline basic steps to implement it.

For Your First Code Contribution

  1. Look for Good First Issues.
  2. Fork the repository and clone it locally.
  3. Work on your changes in a new branch.
  4. Submit a pull request when you're ready.

Improving The Documentation

You can find our Game Design Document (GGD) here.

For improvements you can:

Pull Request Process

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub

Commit Messages with Conventional Commits

Using consistent commit messages helps maintainers and contributors quickly understand the purpose of each change, manage the project more effectively, and collaborate better. This guide will show you how to write clear, meaningful commit messages using the Conventional Commits format.

A commit message example

A commit message is structured like this:

Component Example Description
type feat The type of change (feature, bug fix, etc.).
scope map (Optional) The part of the project affected.
description add player location markers A concise explanation of what the commit does.

Common Commit Types

Type Description Example
feat A new feature feat(map): add player location markers
fix A bug fix fix(api): resolve stats calculation bug
docs Documentation-only changes docs(readme): update contributing section
style Code style changes (e.g., formatting) style(ui): adjust button alignment
refactor Code changes that neither fix bugs nor add features refactor(ui): simplify navigation logic
test Adding or updating tests test(map): add unit tests for markers
chore Maintenance tasks chore(deps): update dependency versions

Example Workflow

Suppose you're adding a new feature to the game map. Your workflow might look like this:

  1. Make changes to the code.
    • Edit the code to implement your changes
  2. Stage your changes:
    • Use the following command to stage all modified files:
    git add .
  3. Write a Commit Message:
    • Use this command to commit your changes:
git commit -m "<type>(<scope>): <description>"
  • Example:
git commit -m "feat(map): add player location markers"
  • Best Practices:
    • Write the commit as a command:
    add player location markers
    Instead of: 
    added player location markers
    • Link issues related to your change:
    fix(map) resolve marker alignment issue
Closes #123
  1. Push your Changes:
git push

Linting and Formatting

We chose to use Ruff to automatically lint and format the code. Run pip install -r requirements_dev.txt to install Ruff and other relevant dependencies.

Important

Before you open a Pull Request, please run this bash commands to format your code properly and doesn't upset our linter:

ruff format . && ruff check --include I --fix . # this formats code and sort imports
ruff check . # run linting and perform fixes
mypy main.py

If you use powershell, run these commands:

ruff format .;
ruff check --include I --fix .;
ruff check .;
mypy main.py