Contribution Workflow

How work moves through the Pengin Open Source codebase — from picking up an issue to landing code in main.

Who this applies to:

• Interns and CLA-signed volunteers — you have GitLab access. Everything on this page applies to you, and all official issue work and pull requests happen on GitLab.
• The general public — you contribute through GitHub. See Public contributions at the end.

For what belongs where in the codebase — an app, main, or util/ — see Contributing. This page is about how work moves.

Terminology: GitLab calls pull requests merge requests. They are the same thing. This page says PR.

---

Why GitLab

The Pengin Open Source community keeps control of its own codebase by running its own GitLab. That is the source of truth: issues, branches, reviews, and merges all happen there.

GitHub is a mirror. It's a public demonstration of the project and an off-site backup — useful, and deliberately secondary. Only protected branches are mirrored to it. Anything that isn't protected stays on GitLab.

---

The issue workflow

Every piece of official work starts from an issue and moves through three branches.

main
 ▲
 │  PR — merged by a senior member or lead developer
 │
issue branch   (tied to the issue)
 ▲
 │  PR — peer reviewed and merged by a maintainer
 │        or senior branch member
 │
working branch (yours)

1. Claim the issue

Find an unassigned issue, volunteer for it, and assign it to yourself. Assigning is the claim — it tells everyone else the issue is taken. Don't start work on an issue assigned to someone else; ask in the issue first.

If you're not sure you can handle it, say so in a comment before assigning. Picking up something too large is normal while you're learning; going quiet on it isn't.

2. The issue branch

Each issue has a branch tied to it — the issue branch. On GitLab, the issue page's Create branch option makes one named from the issue number and title, like 42-fix-slug-delete-redirect, and links it to the issue.

The issue branch is the integration point for that issue. You don't commit to it directly.

3. Work in your own branch

Branch off the issue branch into a working branch of your own:

git fetch origin
git checkout -b stuart/42-slug-delete-redirect origin/42-fix-slug-delete-redirect

A good pattern is <username>/<issue-number>-<short-name>.

One Git rule to know: a branch name can't be a prefix-path of another branch. If 42-fix exists, you cannot create 42-fix/stuart — Git stores branch names as paths, and 42-fix can't be both a file and a directory. Putting your username first avoids the collision.

Commit as you go. Push your working branch to GitLab so your progress is visible and backed up.

4. Open a PR into the issue branch

When the work is done, open a PR from your working branch into the issue branch — not into main.

In the description:

• Reference the issue: Related to #42
• Say what you changed and why
• Say how you tested it — see Contributing
• Call out anything you're unsure of. Reviewers would much rather know.

5. Peer review

A maintainer or senior branch member reviews the PR. Expect comments and requested changes — that is the process working, not a rejection. Push fixes to your working branch; the PR updates automatically.

When it's approved, the reviewer merges it into the issue branch.

6. Resolve the issue

If the issue branch now does what the issue asked for, the issue is resolved, and the issue branch is put forward for consideration to merge into main.

GitLab only closes an issue automatically when a PR merges into the default branch. Since your PR merged into the issue branch, the reviewer closes the issue by hand — note in the closing comment which branch carries the fix.

7. Forward to main

Merging into main is done by a senior member or lead project developer, and usually not one issue at a time.

A PR into main can carry several resolved issue branches together — a batch of fixes considered as a set — or a significant upgrade from one branch. Either way, it's a deliberate decision about what main should become, reviewed at that level rather than per issue.

You don't need to open this PR yourself unless asked. Once your issue is resolved, your part is done.

---

Teams and dev branches

Members are encouraged to form teams and try things.

A dev branch is a space for testing an idea that isn't tied to a single issue — a new approach to the slug editor, a prototype util/ module, an experiment that may not pan out. Name it for the team or idea:

team/editor/json-highlighting
dev/sqs-analytics

Work on a dev branch however suits the team. When an idea proves out, pool the branch work into a PR for submission to main, and a senior member or lead developer reviews it the same way as any other main PR.

Ideas that don't work out are worth keeping around for a while — a failed experiment written down saves the next person from repeating it. Say in the branch or a linked issue what was learned.

---

Where to keep your branches

On GitLab, by default. Personal and team branches belong there.

You can create personal or team branches in public, on GitHub. We encourage GitLab unless there's a reason the general public should see the work — an idea you want outside feedback on, or a project the wider community could join.

When that's the case, ask a maintainer to make it a protected branch. Protected branches are mirrored to GitHub automatically, so the work lives on both — GitLab stays the source of truth, and GitHub gets a public copy for visibility and redundancy.

A branch that exists only on GitHub is outside the community's control and outside the review process. Avoid that for anything official.

---

Rules of thumb

• Official work starts from an issue. If there's no issue, open one.

• Assign before you start; unassign if you stop.

• Never commit directly to an issue branch, a protected branch, or main.

• One working branch per issue.

• Pull the issue branch into your working branch if it moves while you work:

  git fetch origin
  git merge origin/42-fix-slug-delete-redirect
  

• Keep PRs to one concern. Two unrelated fixes are two issues.

• Security fixes never go through public branches. Report them to support@tobupengin.com and work them only on GitLab. See Security.

---

Public contributions (GitHub)

Anyone can contribute through the GitHub mirror — no account on our GitLab required.

Open a PR with a code fix, a feature, an idea, or any other contribution. You can target main, or a public branch a dev team is working on if your change belongs there. For ideas without code, an issue is fine.

A maintainer reviews it on GitHub. Accepted work is applied on GitLab and comes back to GitHub through the mirror, so an accepted PR shows as closed rather than merged — that's expected.

Only protected branches appear on GitHub, so what you see there is the shared, public part of the project. Full details are in Contributing.

---

Related

• Training Syllabus — where issue work fits in the program
• Contributing — code placement and conventions
• Code of Conduct