Contributing

How To Contribute

Creating an Issue

Bug Reports

Before submitting, please review our Reporting Bugs guide for tips on how to identify and report issues effectively.

Feature Requests

Make sure there isn't already an open issue or PR about the feature you're proposing. Check:

• Open issues
• Open pull requests

Creating a Pull Request

Development Setup

Before making your first contribution, run the install command to set up development dependencies:

make install

This installs:

• commitlint - Validates commit message format
• git hooks - Automatically validates commits before push

Line Endings

The repository enforces LF line endings for all text files via .gitattributes (* text=auto eol=lf). This keeps files identical on Windows and inside the Linux containers, and is required for shell scripts and Dockerfiles to run.

You do not need to change your git config — an explicit eol in .gitattributes overrides core.autocrlf, so the result is the same whether yours is true, false, or input. A PR check (Validate Line Endings) fails if CRLF reaches the index.

If you cloned before this policy existed and see CRLF will be replaced by LF warnings, refresh your working tree once. Commit or stash any work first — reset --hard discards uncommitted changes to tracked files (untracked files are left alone):

git rm --cached -r -q .                # clear index entries (does NOT delete files)
git reset --hard                       # re-checkout every tracked file as LF on disk
git ls-files --eol | grep 'w/crlf'     # expect no output

Development Workflow

We use GitHub Flow with automated CI/CD:

Quick workflow:

1. Install dev dependencies (first time only)

   make install

2. Create feature branch from master

   git checkout master && git pull
   git checkout -b feat/my-feature

3. Make changes and commit

   # Make your changes, then stage them explicitly by path
   git add path/to/changed-file
   git commit -m "feat: add cabin management system"

4. Push and open PR

   git push -u origin feat/my-feature
   # Then create a PR on GitHub targeting 'master'

5. After merge - A Build Preview publishes a preview image to DockerHub for testing — automatically on merge when AUTO_BUILD_PREVIEW=true, otherwise on a maintainer's manual dispatch

Commit Conventions

We use Conventional Commits for semantic versioning and automated changelog generation.

Format:

<type>: <description>

[optional body]

Types:

• feat: - New feature (bumps minor version: 1.0.0 → 1.1.0)
• fix: - Bug fix (bumps patch version: 1.0.0 → 1.0.1)
• docs: - Documentation only (no version bump)
• chore: - Maintenance tasks (no version bump)
• refactor: - Code refactoring (no version bump)
• test: - Adding tests (no version bump)

Breaking changes:

• feat!: or BREAKING CHANGE: in body (bumps major version: 1.0.0 → 2.0.0)

Examples:

git commit -m "feat: add cabin management system"
git commit -m "fix: resolve memory leak in server loop"
git commit -m "docs: update installation guide"
git commit -m "feat!: redesign configuration format"

Commit validation:

After running make install, git hooks will automatically validate your commits:

• ❌ Invalid: "update readme" → Error: type missing
• ✅ Valid: "docs: update readme" → Accepted

Making the Pull Request

• PR title should follow commit conventions
• Link related issues in the description (e.g., "Fixes #123")
• Keep changes focused - one feature/fix per PR
• Avoid unrelated changes - no formatting or whitespace changes unrelated to your PR
• Write clear descriptions - explain what you changed and why

We use "Squash and Merge" to combine all commits when merging.

For Maintainers

Repository Setup

1. Configure GitHub Secrets

Go to Settings → Secrets → Actions and add:

Secret	Description
DOCKERHUB_USERNAME	DockerHub username
DOCKERHUB_TOKEN	Create token
STEAM_USERNAME	Steam username (for game download during build)
STEAM_PASSWORD	Steam password
STEAM_REFRESH_TOKEN	Steam OAuth refresh token (optional, preferred over password)

2. Configure Branch Protection

Protect master:

• Settings → Branches → Add rule
• Pattern: master
• Enable:
  • ✅ Require pull request before merging
  • ✅ Require status checks: Validate Build, Validate Commits, Validate Line Endings
  • ✅ Require approvals: 1

3. Configure Fork PR Protection

Settings → Actions → General → Fork pull request workflows:

• Select "Require approval for all outside collaborators"

Troubleshooting

Build Issues

Build fails with Steam auth error:

• Verify STEAM_USERNAME and STEAM_PASSWORD (or STEAM_REFRESH_TOKEN) secrets are set
• Ensure Steam account owns Stardew Valley

Docker push fails:

• Verify DOCKERHUB_TOKEN has read/write permissions
• Check repository sdvd/server exists on DockerHub

Version Issues

Version doesn't bump correctly:

• Check commit messages follow conventional format
• Use git log <last-tag>..HEAD to verify commits
• Commits without feat: or fix: don't bump version

Release PR not created:

• Ensure commits since last tag include version-bumping types (feat:, fix:)
• Check GitHub Actions logs for errors

Resources

• Conventional Commits
• GitHub Flow
• Semantic Versioning
• release-please

Getting Help

• Ask in Discord
• Comment on the relevant issue or PR
• Check existing PRs for examples