Skip to content

Latest commit

 

History

History
146 lines (96 loc) · 7.33 KB

CONTRIBUTING.md

File metadata and controls

146 lines (96 loc) · 7.33 KB

Contributing to Johnny-Knighten/palworld-server

We want to make contributing to this project as easy and transparent as possible, whether it's:

  • Reporting a bug
  • Discussing the current state of the code
  • Submitting a fix
  • Proposing new features
  • Becoming a maintainer

Project Goal

The goal of this project is to provide a simple and easy to use Docker image for running a Palworld dedicated server. The image should have reasonable default settings while also allowing rich configurability for end users.

GitHub

GitHub is used for all project activities. It is used to host code, track issues, feature requests, as well as for managing pull requests.

GitHub Flow is Our Project's Worklow

Pull Requests are the primary way to add changes to the codebase.

General PR process:

  1. Create your branch from the next branch
    • Keep names short and descriptive
    • Name your branch according to what your PR does:
      • feat/
      • fix/
      • refactor/
  2. Develop your feature/fix and write tests were appropriate
  3. Ensure our test suite passes before making a PR
    • Run the bash scripts contained in the tests directory to test changes made to containers
    • If making changes to our CI/CD, run the GitHub Actions workflow locally using nektos/act
  4. Make sure your code lints
  5. Update any related documentation
  6. Create a PR with the merge target as next
  7. Request a review from at least one maintainer
    • All tests must pass for a PR to be approved
  8. Implement any requested changes
  9. Once the PR is approved, the PR is merged into next

We let features collect in next until we feel there is a need to release a new version. We will then merge next into main and release a new version.

If urgent fixes are needed in the current main release, then we will PR merge directly into main depending on the severity of the issue. With that said, also make sure your submitted PR branch is up to date with main and next before submitting your PR.

To leverage automatic CHANGELOG generation via semantic-release we will not rebase or use squash-commits when accepting PRs. We will rely on merge commits to preserve the commit history, even though they clutter history. We have branch rules in place to prevent force pushes to main and next branches. It is recommended to do an interactive rebase before merging your PR to next to clean up your commit history. If you force push into your own (non-protected) branch to clean up its history while in PR review, make sure to inform all assigned reviewers.

GitHub Actions for CI/CD

There are workflows that execute when a PR is open or its code is modified, and all pushes to main and next (when a PR is merged). See build-and-test.yml and release.yml for details.

All tests that are executed in the build-and-test.yml workflow must pass before a PR will be accepted.

Report Bugs Using GitHub Issues

We use GitHub issues to track all bugs. Report a bug by opening a new bug issue.

Coding Style

The number one rule is to keep our code bases consistent. These are the current guidelines we follow, but are subject to change as the project evolves:

  • Use 2 spaces for indentation rather than tabs
  • Delete all trailing whitespace
  • Use meaningful variable names
  • Comment your code where needed, strive to write self-documenting code
  • Lint you code

Commit Messages

We use the Conventional Commits specification for our commit messages. This allows semantic-release to automatically detect version changes and generate changelogs.

The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The <type> and <description> fields are mandatory, the scope of the commit is optional.

Example of a commit message:

feat(database): add 'comments' option

This example indicates that a feature (feat) was added to the 'database' scope of the project.

The two main primary types used to increment the semver are fix: and feat, but some others to consider are build:, chore:, ci:, docs:, style:, refactor:, perf:, and test:.

DockerHub

This project uses DockerHub as our primary container registry to distribute our Docker image.

See our DockerHub repo here.

Testing

Currently we have two test suites, one for the Docker image itself and the other for our GitHub Actions CI/CD workflows.

To run the Docker images locally, first build the image and then run the tests:

# Dependency Tests
$ ./tests/docker_dependencies.sh

# Environment Variable Tests
$ ./tests/docker_environment_variables.sh

To test the GitHub Actions CI/CD workflows locally see cicd-test/README.md for details.

Please always add, remove, and update tests whenever relevant.

Becoming a Maintainer

Maintainers play a crucial role in shaping the project's future and ensuring its stability and direction. Here’s how you can start this journey:

  1. Active Contribution: Regularly contribute to the project through pull requests, bug fixes, and feature enhancements.
  2. Community Engagement: Participate in discussions, help other contributors, and engage with users reporting issues.
  3. Understanding the Project: Gain a deep understanding of the project's codebase, architecture, and roadmap.
  4. Demonstrate Leadership: Show initiative by leading discussions, proposing new ideas, and helping to shape the project's direction.
  5. Express Interest: Reach out to the current maintainers expressing your interest in becoming a maintainer, highlighting your contributions and engagement with the project.

Becoming a maintainer is a responsibility that comes with the commitment to be a steward of the project. It involves more than just technical expertise; it requires dedication to the project and its community.

Submitting PRs Without Being a Maintainer

Only project maintainers will have direct write access to the project's repo. To submit PRs without being a maintainer follow the Fork & Pull Request Workflow.

License

By contributing, you agree that your contributions will be licensed under the project's MIT License.

In short, when you submit code changes, your submissions are understood to be under the same MIT License that covers the project. Feel free to contact the maintainers if that's a concern.

Missing Anything?

If there is anything missing from this guide open an issue and let us know!