Pull requests

Pull requests

This page explains how to propose a change to thaiphon on GitHub. It covers two scenarios: a non-developer contributing a new romanization scheme or a correction, and a developer contributing code.

For non-developers: propose a scheme or correction via the GitHub web UI

You do not need to install anything on your computer. GitHub's web interface lets you edit files and propose changes entirely in the browser.

Step 1 — Create a GitHub account

If you don't have one, go to github.com and sign up. It is free.

Step 2 — Fork the repository

  1. Go to github.com/5w0rdf15h/thaiphon.
  2. Click the Fork button in the top-right corner.
  3. GitHub will create a copy of the repository in your own account. This is your "fork" — you own it, you can edit it freely.

Step 3 — Find or create the file you want to change

For a new romanization scheme, the file belongs in src/thaiphon/renderers/. For example, to add a "Paiboon+" scheme you would create src/thaiphon/renderers/paiboon.py.

In your fork: 1. Navigate to src/thaiphon/renderers/. 2. Click Add file → Create new file (for a new scheme) or click the file name and then the pencil edit icon (for a correction). 3. Write or paste your code. For a new scheme, follow the template in Add a scheme.

Step 4 — Commit your change

At the bottom of the edit page, you will see a "Commit changes" form:

  1. In the first box, write a short description of what you changed, e.g. "Add Paiboon+ romanization scheme".
  2. Make sure "Commit directly to the main branch" is selected (for simple changes).
  3. Click Commit changes.

Step 5 — Open a pull request

  1. Go back to the main page of your fork.
  2. GitHub will show a banner saying your branch is ahead of the original. Click Compare & pull request.
  3. Review the diff — make sure it shows only the changes you intended.
  4. In the title box, write a clear summary: "Add Paiboon+ romanization scheme".
  5. In the description box, explain:
  6. What the scheme is and who it is for.
  7. What sources you used for the romanization conventions (textbook, website, etc.).
  8. A few example words and their expected output.
  9. Click Create pull request.

The maintainer will review your proposal and may ask follow-up questions or request small adjustments before merging.

GitHub's own documentation

If you get stuck, GitHub's guide Creating a pull request from a fork walks through every step with screenshots.

For developers: pull request expectations

If you are comfortable with git, the standard workflow applies:

# Fork on GitHub, then clone your fork.
git clone https://github.com/YOUR_USERNAME/thaiphon
cd thaiphon

# Create a branch.
git checkout -b my-feature

# Make changes, run checks.
make check

# Commit.
git add src/thaiphon/renderers/my_scheme.py tests/test_renderers/test_my_scheme.py
git commit -m "Add <scheme name> romanization scheme"

# Push.
git push -u origin my-feature

Then open a pull request on GitHub.

What reviewers look for

  • make check passes (tests, lint, mypy).
  • New schemes include at least a handful of test cases covering all five tones and a range of vowels.
  • New lexicon entries or derivation fixes include a regression test.
  • Commit messages describe what changed and why, not just what files were touched.
  • No changes to NOTICE or LICENSE unless you have a specific reason.

Commit message style

Write in the imperative mood. The first line is the summary (under 72 characters). Add a blank line and a body if more context is needed:

Add RTGS romanization scheme

Implements the Royal Thai General System of Transcription published by
the Royal Institute of Thailand. No tone decoration (RTGS does not
encode tone). Registered as scheme_id="rtgs".

Reporting a bug

If you found a word that thaiphon transcribes incorrectly but you're not ready to propose a fix yourself, open an issue at github.com/5w0rdf15h/thaiphon/issues.

A good bug report includes:

  1. The Thai word.
  2. What thaiphon currently produces (scheme=, profile=).
  3. What you believe it should produce.
  4. Your source (Wiktionary URL, textbook citation, audio recording, native speaker judgment).

Suggestions from linguists and native speakers are especially welcome.