Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Creating a new Reviewing PRs wiki page #95

Merged
merged 11 commits into from
Feb 24, 2025
38 changes: 38 additions & 0 deletions wiki/ReviewingPRs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
## Reviewing a pull request

Reviewing pull requests is an important part of maintaining Endless Sky and the main way that new content is added to the game. Your feedback helps contributors improve their work and ensures that new content is the best it can be. [This discussion](https://github.com/endless-sky/endless-sky/discussions/10358) covers some great tips for new reviewers.

### Reviewing your first PR

Reviewing PRs is a great first step to getting involved with Endless Sky as a contributor. To begin reviewing your first PR on Endless Sky, please use the resources provided below.

1. Log in to your GitHub account or create one using [this GitHub guide](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github).
2. Follow the steps in [this guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) to reviewing proposed changes in a PR, using [the Endless Sky repository](https://github.com/endless-sky/endless-sky/pulls).

If you have any questions, please feel free to ask on the game's [Discord server](https://discord.gg/ZeuASSx) or by creating or replying to a [GitHub discussion post](https://github.com/endless-sky/endless-sky/discussions).

### General tips when reviewing PRs

* **Use the [wiki](https://github.com/endless-sky/endless-sky/wiki)**: Our wiki is a great resource for all contributors to Endless Sky. When reviewing PRs that change or add new content to the game (e.g. new ships, outfits, artwork, storylines, etc.) please take a look at the [Style Goals](https://github.com/endless-sky/endless-sky/wiki/StyleGoals) and [Quality Checklist](https://github.com/endless-sky/endless-sky/wiki/QualityChecklist) sections of our wiki to make sure that the content fits with Endless Sky's writing and art style.

* **Always read the PR description**: Read the whole thing, and you have a better chance of avoiding making mistakes in your review because you didn't have the background.

* **Don't do reviews as a way to calm down**: Reviewing others' work can be calming, but doing reviews when stressed can also lead you to overreact to relatively small changes. Even if you don't, your reviews will probably be worse than usual.

* **Use the "request changes" button sparingly, or not at all**: In most cases, leaving comments with suggested changes is enough. Developers typically don’t merge PRs with unresolved comments, so there's usually no need to use "suggest changes."

* **Don't review draft PRs. Draft PRs are still a work in progress**: Any feedback you give is likely to be outdated by the time the PR is ready for review, leading to unwanted notifications and overwritten reviews.

* **If you keep making the same correction, check it**: The internet is great for searching up weird grammar and punctuation rules, especially when it comes to American vs British English. ES' source files are great for examining existing precedents within the game itself.

* **Review comments for clarity, not conventions**: Comments in data or code files are mainly read by contributors to the repo and are meant to be understood, not grammatically flawless. If you don't understand a comment, by all means suggest a change to it. But if the meaning's clear, there's no need to nitpick small style issues; better yet, remind the PR author in a single summary comment rather than commenting on every instance.

* **Partial reviews are still helpful**: You may not be able to review every one of the dozens of files in a large PR, but you can still look through one or two files and make a couple of suggestions. Pretty much everyone involved will appreciate it, including the final player.

* **Balance criticism with positive feedback**: Just because you absolutely hate what a PR is trying to accomplish doesn't mean you can't find something good in it. Scathing criticisms are only going to antagonize the author, as well as anyone who actually really liked that PR.

* **Use @ mentions sparingly**: Use it if you're trying to get the attention of people not involved with the PR, if you're writing a PR yourself and want to credit someone else's work, or if someone hasn't responded to your review request or other comments in a while.

* **You don't have to have an opinion on everything**: Express your opinions, but only when doing so will actually accomplish something productive.

* **Be creative**: Your role as a reviewer is not to be Grammarly. To be sure, you should definitely catch out any grammar mistakes you can find, but you should also give constructive suggestions. Don't be afraid to tweak the content of a paragraph to make it flow better. If it doesn't fit what the author is going for, they don't have to use your suggestion. But a suggestion is always better than a "fix this."
1 change: 1 addition & 0 deletions wiki/_Sidebar.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
* [Story Ideas](StoryIdeas)
* [Donations](Donations)
* [Development Vision](https://github.com/endless-sky/endless-sky/wiki/Endless-Sky's-Vision)
* [Reviewing PRs](ReviewingPRs)

**Creation**

Expand Down