Shift-Core Documentation

Contributing Guide

Contributing Guide

This document explains the minimum rules required to contribute to the ShiftCore Team Handbook.

For detailed explanations, examples, and full workflow steps, check the related documents inside docs/.

Main Rule

Do not push directly to main.

Every change must go through:

Branch → Commit → Pull Request → Review → Merge

This applies even to small documentation changes.

Basic Workflow

  1. Create a new branch.
  2. Make your changes.
  3. Write a clear commit message.
  4. Push your branch.
  5. Open a Pull Request into main.
  6. Request review from a teammate.
  7. Fix review comments if needed.
  8. Merge only after approval.

For the full workflow, see:

docs/git/git-workflow.md

Branch Naming

Branch format:

type/short-task-name

Examples:

docs/update-readme
docs/add-git-workflow
fix/typo-in-start-here
chore/update-handbook-structure

For full branch naming rules, see:

docs/git/branch-and-commit-rules.md

Commit Messages

Commit format:

type(scope): short message

The scope is optional.

Examples:

docs: add setup instructions
docs(handbook): add git workflow
fix(readme): correct typo
chore(structure): add documentation folder

Avoid unclear commit messages like:

update
fix
final
new
changes

For full commit rules and examples, see:

docs/git/branch-and-commit-rules.md

Pull Requests

Every change must be submitted through a Pull Request.

A good Pull Request should explain:

  • What changed?
  • Why was it needed?
  • How can it be reviewed?

For full Pull Request rules, see:

docs/git/pull-request-guide.md

Code Review

At least one teammate should review the Pull Request before merge.

The reviewer should check:

  • Is the change clear?
  • Is the file in the correct location?
  • Is the wording understandable?
  • Are there typos?
  • Does it follow the agreed rules?

For full review rules, see:

docs/git/code-review-guide.md

Merge Rules

  • Do not merge without approval.
  • Do not merge if there are unresolved comments.
  • Do not merge if the Pull Request has conflicts.
  • The Pull Request author is responsible for merging after approval.
  • If the author is unavailable, a reviewer or team lead may merge only after confirming the PR is ready.

Documentation Rules

Keep documentation:

  • Clear
  • Short
  • Organized
  • Easy to update
  • Not duplicated across many files

For documentation standards, see:

docs/documentation/documentation-standards.md

Definition of Done

A contribution is done when:

  • The change is in the correct file.
  • The branch name follows the agreed format.
  • The commit message is clear.
  • A Pull Request is opened.
  • A teammate reviews it.
  • Review comments are resolved.
  • The Pull Request is approved.
  • The Pull Request is merged into main.