Josh Goldberg
Logo of create-typescript-app: the TypeScript blue square with rounded corners, but a plus sign instead of 'TS'

Contributing to a create-typescript-app Repository: FAQs

Oct 20, 202315 minute read

FAQs for contributing to my create-typescript-app project or any repository scaffolded using it.

create-typescript-app is a project of mine that provides a comprehensive template for any TypeScript repository. Contributing to a create-typescript-app Repository covers the general flow for contributing to those repositories. This article is a collection of the frequently asked questions (FAQs) for that flow.

Got your own question not covered here? Iā€™d be happy to answer it - let me know!

Asking Questions

ā¤ļø Definitely ask questions! The best way to do so depends on what youā€™re working on.

How confident in my changes should I be before sending a PR?

You donā€™t have to be 100% confident in your changes. Do your best to get building, linting, and tests -including added unit tests- working as much as you can.

See Iā€™m having a hard time, how do I ask for help? for more information.

Iā€™m having a hard time, how do I ask for help?

If the documentation on a repository is unclear about something, please file a docs issue on the repositoryā€™s issue tracker. Youā€™re probably not the only person with that docs issue. Filing an issue helps ensure you get an answer and the docs get fixed.

If youā€™re confused reading an issue on an issue tracker, please ask for clarification on the issue. Youā€™re probably not the only person with that confusion. Asking on the public issue lets anybody else confused about the same point learn along with you.

If youā€™re working on a pull request, Iā€™d recommend posting a comment thread on the file or line of code you want to ask for help with. A maintainer will answer the question as part of reviewing the pull request. Note that draft PRs generally arenā€™t reviewed, so make sure the PR is un-drafted if youā€™d like your questions answered.

For any other questions on repositories, see if the repository has a dedicated support forum, such as Discord. If it doesnā€™t, and Iā€™m a maintainer on the repository, you can reach out to me wherever you find me. My links are on the homepage of joshuakgoldberg.com and on my GitHub @JoshuaKGoldberg profile. I look forward to hearing from you!

TODO HIT ME UP GIF

Git and GitHub

The GitHub docs are excellent for learning about both. Their Set up Git guide is particularly useful for working with it locally.

I cloned a upstream repository without forking

Thatā€™s ok! Youā€™ll need to update what your local repository thinks of as its ā€œremotesā€ (remote repository equivalents).

Run git remote -v to see all your remotes. You might see something like:

$ git remote -v
origin  https://github.com/JoshuaKGoldberg/create-typescript-app.git (fetch)
origin  https://github.com/JoshuaKGoldberg/create-typescript-app.git (push)

Use the following Git commands to rename the origin remote to upstream, then add your own origin after:

git remote rename origin upstream
git remote add origin https://github.com/YourUsername/create-typescript-app

Running git remote -v again should show updated entries like:

$ git remote -v
upstream  https://github.com/JoshuaKGoldberg/create-typescript-app.git (fetch)
upstream  https://github.com/JoshuaKGoldberg/create-typescript-app.git (push)
origin  https://github.com/YourUsername/create-typescript-app.git (fetch)
origin  https://github.com/YourUsername/create-typescript-app.git (push)

I get 403 / permissions errors trying to git push

Do you see anything like this?

$ git push -u origin my-branch
remote: Permission to JoshuaKGoldberg/create-typescript-app.git denied to YourUsername.
fatal: unable to access 'https://github.com/JoshuaKGoldberg/create-typescript-app.git/': The requested URL returned error: 403

If the ā€œremoteā€ being pushed to isnā€™t a repository under your username, then you might have missed a step in forking the repository. Fork the repo on GitHub, then see I cloned a upstream repository without forking.

If the ā€œremoteā€ being pushed to is a repository under your username, then your local Git might not have permissions to push to your account on GitHub. Consider using the GitHub CLI to make permissions settings easier to work with.

I sent a pull request from main, how do I change the pull request to be from a branch?

I donā€™t think thereā€™s a way to update what branch a PR is being sent from (its ā€œheadā€). Iā€™d recommend creating a new branch with your changes, sending a new PR from that new branch, and closing the old PR from your main. The following Git commands will make a new branch (my-new-branch) on your local and origin repositories, then reset each repositoryā€™s main branch to the upstreamā€™s main.

git checkout -b my-new-branch main
git push -u origin my-new-branch
git checkout main
git reset --hard upstream/main
git push --force

How do I reset my main back to the upstreamā€™s?

Are you getting errors trying to update your local or origin repositories to the upstream?

$ git pull upstream main
From https://github.com/JoshuaKGoldberg/create-typescript-app
 * branch            main       -> FETCH_HEAD
fatal: Not possible to fast-forward, aborting.

Those errors indicate that your local repositoryā€™s main has its own commits not present on the upstreamā€™s. This is why I donā€™t recommend sending PRs from a main branch. After a PR is merged into the upstream repositoryā€™s main, its history will be different than your mainsā€™.

Run the main-related commands from I sent a pull request from main, how do I change the pull request to be from a branch?:

git checkout main
git reset --hard upstream/main
git push --force

Why do you squash merge pull request branches?

In short: I donā€™t want to burden contributors with keeping clean Git histories. Squashing PRs means we donā€™t care about the granular commits. We only need to care about the PR title, description, and latest files diff.

In more detail: I prefer pull requests be small and single-purpose. Itā€™s very rare that a single PR is big enough that it would benefit from a clean commit history. This is especially true in the small-to-medium-sized projects targeted by create-typescript-app.

Some repositories ask that pull requests have a clean Git history, meaning each commit has a discrete change and clear message explaining the change. Clean Git histories in a PR can make it easier to review the pull request. Merging a clean Git history into the default branch can make it easier for future developers to understand how the changes within the pull request came to be.

One downside of keeping a clean Git history is that it requires pull request authors to do more work to keep the history clean. Thatā€™s extra work even when the history doesnā€™t need to be rewritten. And when it does need to be rewritten then developers not familiar with Git may have a hard time working with Git.

Therefore, I donā€™t consider the benefits of a clean Git history to be worth the drawbacks in my repositories.

Why donā€™t you want me to git push --force to a pull request branch?

Most of the reasons why developers rewrite history in a PR branch involve curating a clean Git history. Per Why do you squash merge pull request branches? that commit history is generally not necessary or asked for in my repositories.

On the other hand, there are two main downsides to force pushing to an active pull request:

I personally also like showing how messy my Git history gets. I donā€™t like the idea of new developers seeing a cleaned up history and thinking all experienced developers do work like that naturally. Itā€™s an unrealistic standard of code cleanliness.

Repository Tooling

My files arenā€™t formatted on commit

Did you run pnpm install? If dependencies were installed, the repositoryā€™s tooling should have set up a Git commit hook to automatically format files with Prettier on save.

Here are a few other remediations:

  1. Try removing the node_modules/ directory and re-running pnpm install.
  2. If that passed but didnā€™t fix the issue, try running pnpm run prepare manually.
  3. If that passed but didnā€™t fix the issue, try filing an issue on the repository.

My files arenā€™t formatted on save in VS Code

Did you run pnpm install and install the Prettier VS Code extension? If dependencies were installed, the editor.codeActionsOnSave and editor.defaultFormatter settings from the repositoryā€™s .vscode/settings.json file should be telling VS Code to format files when you save them.

Here are a few other remediations:

  1. Try uninstalling the Prettier VS Code extension, installing it again, and then restarting VS Code.
  2. If that didnā€™t work, try removing the node_modules/ directory and re-running pnpm install.
  3. If that passed but didnā€™t fix the issue, try filing an issue on the repository.

When should I use Vitest snapshots?

See the Vitest test snapshots docs. In general, if thereā€™s some test value or function that would be inconvenient to manually craft test assertions for. Common cases include:

I generally prefer toMatchInlineSnapshot so that the values are visible in the test itself.

Other

Why are there so many tools in your repositories?

Because theyā€™re useful! šŸ™Œ

I know that having to learn and work with so many tools can be painful. It takes time when you get started, slows down development when they complain, and generally make the repositories harder for new contributors to contribute to. That brings me pain. šŸ˜¬

But! Each of the tools brings real benefit to the repository. The issues they prevent are things that often need to be flagged in pull requests - which means they often become bugs or typos discovered later. I believe these tools net save time by automating catching those issues.

Furthermore, itā€™s useful for the ecosystem for repositories to use the latest and greatest in tooling. Using these tools provides valuable feedback for their projects and maintainers, which helps the industry learn and grow. That brings me joy. šŸ’“

Why is there so much to read in this guide?

My repositories donā€™t have much more to do in setup or contributing than most other repositories. Iā€™ve just explicitly written out many of the things that are implicitly assumed in most repositories. Reading through the guide now will save you a ton of time later on. I promise.


Got your own question not covered here? Iā€™d be happy to answer it - let me know!