Git Workflow¶

If you’re planning to contribute to OmegaT — whether it’s code, documentation, or translation — we’re happy to have you on board!

We use Git as our version control system, and our project is hosted on GitHub:
👉 https://github.com/omegat-org/omegat

This guide walks you through how to contribute using Git and GitHub, even if you’re new to them.

Git documentation: https://git-scm.com/docs

GitHub documentation: https://docs.github.com/en/repositories

Where Development Happens¶

The main development takes place in the master branch of the repository.
When working on a contribution, create a separate branch from master. This is called a topic branch.

✅ Good Branch Naming¶

Use the following format for naming your topic branch:

topic/your-username/area/short-description

Examples:

topic/charlotte/editorpane/fix-keybindings
topic/philippe/docs/add-plugin-guide

Clear naming makes it easier for everyone to understand your work at a glance.

Avoid names like:

fix
patch-1
change
my-branch

Such names do not give any indication of what your work is about.

Clone the OmegaT code on your machine¶

If you work with Git¶

Clone the OmegaT repository:

   git clone https://github.com/your-username/omegat.git
   cd omegat

Create your topic branch:

   git branch topic/your-username/area/short-description

Switch to your topic branch:

   git switch topic/your-username/area/short-description

If you work with Github¶

Fork the OmegaT repository
Visit: https://github.com/omegat-org/omegat Click the “Fork” button in the top right.
Clone your fork:

   git clone https://github.com/your-username/omegat.git
   cd omegat

Add the main repository as an upstream:

   git remote add upstream https://github.com/omegat-org/omegat.git

Create your topic branch:

   git branch topic/your-username/area/short-description

Switch to your topic branch:

   git switch topic/your-username/area/short-description

✅ Before submitting your code¶

🔍 Check What You Changed¶

Use our custom Gradle task to check which files you’ve modified.

In your IDE:

Open the Gradle Tasks panel
Expand omegat workflow
Run changeOnBranch

From the terminal:

Run ./gradlew changeOnBranch

🎨 Format Your Code¶

Use Spotless to automatically format only your changes.

In your IDE:

Open the Gradle Tasks panel
Expand omegat workflow
Run spotlessChangedApply

From the terminal:

Run ./gradlew spotlessChangedApply

This ensures your code follows the project’s style and avoids noisy diffs.

📬 Submit Your Code¶

If you work with Git only¶

Create a Git patch for your code:

   git diff

Attach the patch to the relevant issue on Sourceforge:

You are supposed to work on an issue that you either responded to or registered yourself on Sourceforge.

Inform the development list that you sent a patch:

You’re supposed to have discussed your code on the development list before starting to write, so use the same thread.

If you work with Github¶

Push your topic branch to GitHub:

   git push origin topic/your-username/area/short-description

Open a Pull Request:

Visit your fork on GitHub
Click “Compare & pull request”
Add a clear title and explanation
Link to any related issues or discussions

Tip: You can open a draft pull request if you’re still working on it but want feedback early.

✅ After You Open a Pull Request¶

Once you submit a pull request (PR), GitHub will automatically run our Continuous Integration (CI) checks.

These checks ensure that your contribution builds successfully and follows the project’s standards. If something goes wrong, GitHub will show it — but you need to check it yourself and make any necessary fixes.

📋 Where to Check the CI Results¶

After opening a PR:

Scroll down to the Checks section (below the PR description).
Click the “Details” link next to any failed check, such as:
- Quality checks
- SpotBugs
- PMD
- checkStyle
- Acceptance Test
GitHub will open a log page that shows:
- What failed
- On which file and line
- Sometimes with inline annotations

⚠️ What to Look For¶

Check Name	What It Means	Common Fix
`Quality Checks`	Tests and checks are failed	It send Gradle Scan® to web site. You can open details in Gradle Velocity
`SpotBugs`	Logic uses wrong habit	Run `./gradlew spotbugsMain spotbugsTest` and fix issues
`PMD`	Out of the coding best practice	Change your code according to the annotated suggestions
`checkStyle`	Code violates style rules (Checkstyle)	Run `./gradlew checkStyleMain checkStyleTest` and fix issues
`Acceptance test`	Acceptance tests failed	Run `./gradlww testAcceptance` and fix issues

🛠 Fixing the Issues¶

If the CI check failed, you are expected to fix the problem yourself.

Do not wait for someone to tell you what to do. Use these steps:

Read the error message.
Open the file and line number referenced.
Reproduce the issue locally:

# Build and test
./gradlew build

# Run Checkstyle
./gradlew checkStyleMain checkStyleTest

Fix the issue.
Recommit and push:

git add .
git commit -m "Fix checkstyle | spotbugs | unit test errors"
git push

Pushing a new commit will automatically rerun the checks.

✨ Code Formatting: Do This Every Time¶

Before committing your changes, run this to auto-format your modified files:

./gradlew spotlessChangedApply

This prevents many common CI failures and makes the code easier to review.
You can also set up automatic formatting in your IDE using the project’s Spotless rules.

🔁 Re-running CI Manually¶

If a CI check fails for unrelated reasons (e.g. flaky network or timeout):

Go to the Checks tab of your pull request.
Click “Re-run jobs” > “Re-run all jobs” or “Re-run failed jobs”.

✏️ Why This Matters¶

CI checks are not optional. If your PR fails them:

It will not be reviewed until all checks pass.
Reviewers are not responsible for fixing your code.
Ignoring CI feedback delays your contribution and others’.

Learning to understand CI is part of modern software development — and it’s a required skill for contributing to OmegaT.

❤️ Still Need Help?¶

If you’ve tried but are stuck:

Copy the exact error message
Say what you did to try to fix it
Ask clearly on the developer mailing list

We’ll be glad to help — if you show that you’ve made an effort first.

🙌 Thank You!¶

Thank you for contributing to OmegaT — your work helps make it better for everyone.