Code Contributions Feedback¶

This section is a required reading for any person who wants to provide feedback on contributions.

🛠 Volunteer work¶

OmegaT development is based on volunteer work. Most of the contributions are made by people on their free time.

Providing feedback on a contribution is also a contribution to OmegaT.

Contributing to OmegaT requires being able to keep a good balance between your private life and the time you spend on your contributions.

Just as any volunteer work, contributing to OmegaT means that:

you are a reasonably well-organized person
you generally know how to set priorities
you are able to hand off a task when you can’t commit yourself to it anymore
you are generally not afraid to ask for help
you are usually fine with receiving unrequested help

To ensure that code contribution feedback is constructive and keeps OmegaT development moving forward, here are a few important rules.

🗺 Locations¶

Code contributions are discussed and implemented in three main spaces:

The development list
The tracker system
The GitHub repository Pull Requests section

Depending on its implementation stage, the best place to comment on a contribution will vary.

Early stage comments are appropriate on the development list, in a relevant thread
Specific implementation discussions are appropriate on the tracker system
Issues with the implementation itself are appropriate on the Github Pull Requests section

It is best to keep comments compartmented this way but it is sometimes useful to refer to a pull request on the development list or the tracker system, etc., either to discuss related issues or to draw attention to specific items.

The development list is our only official space to discuss and comment on contributions and it is the place where all comments and discussions are allowed to come back to. Only the tracker system and the pull request section have scope limitations.

😊 Manners¶

Regardless of the space in which they are made, comments on contributions must always be respectful, relevant and clear.

This is a requirement to keep development productive and enjoyable for everyone.

🎯 Scope¶

Each contribution typically aims to fix a specific problem or introduce a clearly defined feature. When commenting on a contribution, please:

Read the contribution carefully.

The contribution usually comes with a description. The description explains the contribution’s purpose and scope.

Comment only on things directly related to that purpose and scope.

If you discover a seemingly unrelated issue, make a note of it and consider which is the appropriate space to address it.

Since all development-related discussions are welcome on the development list, do not hesitate to come back to the list, in a relevant (or new) thread to address that new issue.

Keep in mind that:

Specific implementation discussions are appropriate on the tracker system
Issues with the implementation itself are appropriate on the Github Pull Requests section
Do not hijack discussion threads, with unrelated issues

If you are not sure whether an issue is related to the contribution or not, ask on the development list in a clearly identified thread.

🧪 Reports¶

If you’re testing a contribution and something doesn’t work as expected:

Describe clearly what you did, what happened, and what you expected.
Ask for confirmation whether the issue is part of the contribution scope.
Do not post raw logs in an early report.

Logs include a lot or non-relevant information and unless you know which section is relevant to the issue at hand, do not attach them to a report. Eventually, you will be asked to provide a log if the contributor cannot reproduce your issue.

✅ Good report:
“When I tested the new caching feature with glossary lookup, I noticed that the refresh button didn’t seem to respond. Is that expected?”

💬 Constructive Comments¶

When reviewing the code itself (even if you’re not a programmer), you can still help by:

Asking for clarification when something is unclear.
Noting typos, confusing wording, or behavior differences.
Suggesting improvement with context, not just pointing out flaws.

✅ Good comment:
“I expected the text to auto-save after editing, but it didn’t. Is this part of the feature or a known limitation?”

🤝 Respect¶

In small open-source teams, it’s common for one person to wear many hats: developer, tester, reviewer, and even project manager. Still:

Let the contribution author respond first to comments or questions.
Give the reviewer space to evaluate the code’s quality and integration.
Avoid interrupting the review with unrelated findings.

This helps reduce confusion and avoids discouraging contributors who volunteer their time and skills, just like you.

🔄 Keep the flow¶

Sometimes, reviewers suggest improvements like “we need to write better docs here” or “this should be updated later”. These are helpful suggestions, but only if followed through.

In such cases, both the reviewer making the suggestion and the contributor can act. The contributor can act on that suggestion, or ask the reviewer to help, or send a help request to the development list.

If the person making the suggestion doesn’t act — or if the contributor isn’t clear on what to do — progress stalls.

To keep development flowing:

Be organized. Take note of what you did, what you suggested, what you promised, put that in a calendar system to make sure that you are not overwhelmed by what you want to commit yourself to.
Set priorities. If you suggest something, make sure you can follow up. If you get too busy with life, send a notice and/or hand off the task.
Support contributors. If someone hesitates or is unsure about an issue, help them to complete their tasks.
Do not stall the contribution by promising something and then forgetting about it. Be organized, set yourself deadlines and hand off the task when you see that you really can’t handle it.

🤝 A good reviewer helps motivate contributors and keeps energy moving forward.

✅ Summary¶

When commenting on contributions:

✅ Focus on
Staying within the contribution’s scope
Writing clear, respectful feedback
Reporting test results clearly
Letting the contribution author reply
Keeping progress moving with clear actions
——————————————–

We all want to improve OmegaT together — thoughtful communication helps us grow as a team and support each other’s contributions with mutual respect. 💙