Issues, Projects, Forks and Open Source

The portfolio is on GitHub and changes reach main through pull requests. Two questions remain. How do you keep track of what to do next, without a sticky note on your monitor? And how do you contribute to a project you don’t own, where you can’t even push a branch? GitHub answers the first with issues and Projects, and the second with forks.

Issues: work you can link to

An issue is a tracked piece of work: a bug, a feature idea, a question. Each gets a number shared with pull requests (#12), a discussion thread, and metadata:

• Labels categorise it: bug, enhancement, documentation, good first issue.
• Assignees say who’s on it.
• Milestones group issues toward a goal, such as “Launch v1”.

For your portfolio, write the to-do list as issues: “Projects page: filter by tag (#12)”, “Footer overlaps content on mobile (#13)”. Then each pull request names its issue with Closes #12, merging closes it, and six months later anyone can follow the trail from a line of code to the commit, the pull request, the discussion and the original reason.

A good bug report has steps to reproduce, what you expected, what happened, and the browser or version. Repositories can add issue templates in .github/ISSUE_TEMPLATE/ so reporters fill those sections in automatically.

Projects: the board above the issues

A GitHub Project is a planning view over issues and pull requests, possibly from several repositories. It starts as a spreadsheet-like table; you add custom fields such as Status, Priority, Size or Iteration, and switch between table, board (columns by Status, the familiar kanban) and roadmap (items on a timeline) layouts. Built-in workflows can move items automatically, for example to Done when an issue closes or a pull request merges.

For a solo portfolio, a board with Todo, In progress and Done is plenty. On a team, the Project is where planning conversations happen and the issues hold the detail.

Forks: contributing without write access

Say you’ve found a typo in the docs of an open-source theme library, open-themes/vite-themes. You can clone it, but you can’t push to it: you’re not a collaborator, and git push fails with a permission error. That’s what forks solve.

A fork is your own copy of the repository on GitHub, under your account: maya-okafor/vite-themes. You can push anything to it. When your change is ready, you open a pull request from a branch on your fork to the original repository, which by convention is called upstream.

Here’s the whole routine:

# 1. Click Fork on github.com/open-themes/vite-themes, then clone YOUR fork
git clone git@github.com:maya-okafor/vite-themes.git
cd vite-themes

# 2. Remember where the original lives
git remote add upstream https://github.com/open-themes/vite-themes.git
git remote -v    # origin = your fork, upstream = the original

# 3. Work on a branch, never on main
git switch -c fix-readme-typo
git commit -am "Fix typo in installation steps"
git push -u origin fix-readme-typo

GitHub then offers “Compare & pull request” on your fork. Check that the base repository is open-themes/vite-themes and the base branch is their main. The CLI shortcut for steps 1 and 2 is gh repo fork open-themes/vite-themes --clone, which also sets up the upstream remote for you.

Leave “Allow edits by maintainers” ticked when you open the pull request. It lets maintainers push small fixes to your branch instead of asking you for every tweak.

Keeping your fork current

The original keeps moving. Bring its changes into your fork before starting each new branch:

git fetch upstream
git switch main
git merge --ff-only upstream/main
git push origin main

Because you never commit on your fork’s main, this is always a fast-forward. The Sync fork button on your fork’s GitHub page, or gh repo sync maya-okafor/vite-themes, updates the GitHub copy; you still pull it locally. (Plain gh repo sync with no argument updates your local clone instead.)

Being a welcome contributor

Before writing code, read the project’s README and CONTRIBUTING.md (setup, tests, style, whether an issue is required first) and its code of conduct. Search existing issues and pull requests; your bug may already be known or fixed. For anything bigger than a typo, open or comment on an issue and agree on the approach before writing code. Issues labelled good first issue are deliberately picked as starting points.

Then keep the pull request small, follow the project’s conventions even where you’d choose differently, make sure its tests pass, and answer review comments patiently. Maintainers are often volunteers. A focused, well-described pull request that’s easy to say yes to is the best introduction you can make.

That completes the collaboration toolkit. In the last section you’ll pick up the habits that make all of this safe: undoing mistakes, keeping the repository clean, writing history people can read, and letting automation guard main.