Skip to content

Commit

Permalink
Updated maintainer/pr policy, Added new release documentation (#315)
Browse files Browse the repository at this point in the history
  • Loading branch information
Jezithyr authored Oct 4, 2024
1 parent cbc5445 commit 415a4c1
Show file tree
Hide file tree
Showing 7 changed files with 75 additions and 40 deletions.
7 changes: 5 additions & 2 deletions src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ General Development
- [Pull Request Guidelines](en/general-development/codebase-info/pull-request-guidelines.md)
- [Codebase Organization](en/general-development/codebase-info/codebase-organization.md)
- [Acronyms & Nomenclature](en/general-development/codebase-info/acronyms-and-nomenclature.md)
- [SS14 Release Model](en/general-development/codebase-info/releases.md)
- [Tips](en/general-development/tips.md)
- [Beginner FAQ](en/general-development/tips/beginner-faq.md)
- [Troubleshooting FAQ](en/general-development/tips/troubleshooting-faq.md)
Expand Down Expand Up @@ -322,11 +323,13 @@ Staff
----------------------
- [Project Manager](en/wizden-staff/projectmanager.md)
- [Maintainer](en/wizden-staff/maintainer.md)
- [Review Policy](en/wizden-staff/maintainer/wizards-den-review-policy.md)
- [Review Policy](en/wizden-staff/maintainer/maintainer-policy.md)
- [Reviewing Procedure](en/wizden-staff/maintainer/review-procedure.md)
- [Hotfix Procedure](en/wizden-staff/maintainer/hotfix-procedure.md)
- [Space Wizards Role Hierarchy](en/wizden-staff/space-wizards-role-hierarchy.md)
- [Space Wizards Maintainer List](en/wizden-staff/space-wizards-maintainer-list.md)
- [Maintainer Policy](en/wizden-staff/maintainer-policy.md)
- [Staff Policy](en/wizden-staff/staff-staff-policy.md)
- [Staff Policy](en/wizden-staff/staff-policy.md)
- [Staff Conflict Resolution](en/wizden-staff/staff-conflict-resolution.md)

Maintainer Meetings
Expand Down
23 changes: 23 additions & 0 deletions src/en/general-development/codebase-info/releases.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Release Process
Space Station 14 uses a rolling release model for updating the servers. **Updates are deployed every 14 days** onto the "stable" branch, while development takes place on the "master" branch. For urgent bugfixes, **hotfixes are pushed nightly** from the "stable" release branch or immediately *if the fix is critical*. **Content on the development "master" branch is *not fully commited to*** and may be removed or held back from the next update.

What does this mean for you? If you're a fork developer, this means that you now have the choice to pull from the *more stable* release branch, *or* pull from the latest development branch to get the latest changes even if they might change or get reverted. If you're a contributor or upstream maintainer, this means that your changes won't immediately be pushed to live (unless they qualify as a bug fix). If you're a player this means that there will be larger but less frequent updates that have more content, while the daily updates will be limited to bugfixes.

## How does this work?
### Deploying Updates
Updates are deployed every 14 days over the course of a weekend (Usually on a Saturday). 2 days prior to update day, "master" will be branched into "staging" and maintainers will perform a review of the upcoming changes. During this period, changes may be made or PRs may be reverted on the staging branch. Release day also coincides with the day of the regular maintainer meeting, half of which will be devoted to looking over the changes prepared for release. The outcome of this meeting determines if the update will be deployed as is, receive changes, or be delayed. The following 2 days after an update is deployed will allow for balance/minor gameplay fixes to be deployed under the normal Hotfix procedure.

### Review/PR Procedure
All PRs must be reviewed according to the PR review procedure [documented here](../../wizden-staff/maintainer/review-procedure.md), and may be merged to the development branch "master" at any point. PR's fixing code bugs or critical gameplay issues *may* be merged directly onto the "stable" branch but in that case must additionally follow the Hotfix procedure [documented here].

### What is Hotfixable?
Any issue that directly impacts a player's ability to play the game in a largely negative way and can be considered by most to be a "bug" is eligable to be merged as a Hotfix. Critical gameplay issues may also fall into this category as well. "Critical" being an issue that is majorly disruptive to players **or admins**. *Outside of an emergency*, all **Hotfixes require 3 maintainers to sign-off** on merging (Ideally they should also review but giving approval is enough). Bugfixes may be applied to master following the regular review requirements.

### Branching
There are *three* branches that are used in this process:

**Master:** This is the primary development branch and where PRs normally get merged into. Content in the development branch is not final and may be reverted or changed before ending up being released. This branch should generally not be used for hosting a server or as an upstream since it is not guarunteed to be stable and may have reverts.

**Stable:** This is the "release" branch that the wizden servers run off of. Content in this branch should generally be considered "commited" and won't be reverted except for in exceptional circumstances. This is the branch you should use as an upstream or if you are hosting a server. Only bugfix PR gets directly merged into this branch, content PRs are merged into "master" and then the entire branch is deployed to "staging" and then merged into "stable".

**Staging:** This is a special branch mainly only used for preparing updates. During the update period (2 days leading up to the release), this branch will be pulled off from "master" to review the merged PRs in preparation for the release. Any changes/reverts needed for the release will be made in/to the "staging" branch which will be merged into the "stable" and "master" branches on update day. When not preparing an update, the staging branch is not used.
33 changes: 0 additions & 33 deletions src/en/wizden-staff/maintainer-policy.md

This file was deleted.

13 changes: 13 additions & 0 deletions src/en/wizden-staff/maintainer/hotfix-procedure.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Hotfixing Procedure
This does not apply to rule change or server config change PRs from the Head Game Admins. In an emergency these requirements may be waived with written permission from a project manager.
Not following this procedure/policy will result in disiplinary action being taken.
## Requirements
- **Three maintainers must *sign-off*** (Aproval is required, reviewing is reccommended but optional) on a hotfix PR for it to be merged. This can be bypassed in an emergency, for a critical fix.
- The Hotfix procedure only applies to PRs being merged straight to "stable". **When merging bugfixes to master, this procedure does NOT apply, use the normal PR procedure instead!**
- All Hotfixes must adhere to the normal [PR Review Procedure](../maintainer/hotfix-procedure.md) in addition to any requirements listed here.
- Hotfixes must be tagged with the "Hotfix" and relevant department/game area tags.
- Hotfixes are for fixing bugs only and not adding new content or minor balance adjustments. *If a balance issue is bad enough to majorly impact game quality, it should be considered a bug and is eligable for a hotfix. This is up to maintainer judgement, but if you are unsure it's recommended to create a discussion thread prefixed with "HOTFIX-PRNumber".
## Policy
- Whether a PR should be classifed as a bug fix or not is up to the maintainers reviewing the PR. But in general, a bug fix adjusts existing content/code to fix an issue without dramatically changing the game or adding new content.

- Balancing changes are usually not bug fixes. A balancing change adjusts tuning values on a gameplay system/mechanic to change gameplay to be more in line with the intended experience. If the experience before the change is still playable then the balancing change is not a bug fix, however if the gameplay is *causing major issues for players/admins* then a balancing change can be considered as a bugfix in this case.
12 changes: 12 additions & 0 deletions src/en/wizden-staff/maintainer/maintainer-policy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Maintainer Policy
This is the policy that all maintainers are expected to follow when it comes to behavior and responsibilities.

This policy applies in addition to the [General Staff](../staff-policy.md) and [Conflict Resolution](../staff-conflict-resolution.md) Polices.

**Breaking any of these rules will result in disiplinary action being taken**
## Reviews and Feedback
- All maintainers must follow the [PR Review](../maintainer/review-procedure.md) and [Hotfix Procedures](../maintainer/hotfix-procedure.md) when they apply.
- Maintainers should try to the best of their ability, to keep PR authors informed on the status of their PRs.
- Maintainers should keep public criticism of code *constructive* and avoid making comments in regards to the authors of the code. **Harsh but fair** citicism of code is *acceptable*, but criticism of it's author is not.
- Maintainers should try to perform code reviews *whenever possible*, getting content into the game is everyone's responsibility.
- If there is a conflict around game design between something in the docs and someone's idea, what is detailed in the documentation takes precedent. If a change to specific documentation is needed, it should be brought up with the respective work group for discussion and changes should be made to the documentation if needed.
22 changes: 22 additions & 0 deletions src/en/wizden-staff/maintainer/review-procedure.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# PR Review Procedure
This does not apply to rule change or server config change PRs from the Head Game Admins. In an emergency these requirements may be waived with written permission from a project manager.
Not following this procedure/policy will result in disiplinary action being taken.
## Requirements
- All PRs *should* adhere to the [code conventions](../../general-development/codebase-info/conventions.md), but this is not a hard requirement since some specific usecases may require straying from convention for readability.
- PRs must be properly tagged with the relevant department/game areas.
- PRs affecting gameplay must reference a design doc/proposal. For smaller changes, the design may be outlined in the PR description. All gameplay PRs must not conflict with the core game design and should ideally reference how they fit into it.
- PRs primarily fixing bugs must be tagged with the "Bug Fix" tag.
- **2 Maintainers are required to review/sign off on merging a PR**. *This requirement may be waived with written permission from a PM when the situation warrants it.*
## Policy
- When reviewing a PR assign it to yourself to let others know that you will be "owning" the PR. If you decide to stop owning the PR, un-assign yourself so that others may take over the PR. By owning a PR you are taking responsibility for keeping track of the PR's progress and keeping the PR author informed of what is the status of the review process. Anyone may review an owned PR, however before taking action talk with the owner first. *If changes are approved by the "owner" any maintainer may merge the PR if they also approve the changes.*

- If you think a PR warrants further discussion with maintainers, you may **optionally** create a review thread in maint-reviews. *This is not a requirement*, but is recommended when you aren't sure about something. If you do this, make sure to tag the PR with the "In Discussion" tag, and summarize the result of the discussion in the PR *before* taking any action(Such as merging or closing). The discussion thread should have the PR number in the title, and a link to the PR included within. You should also be appropriately tagging the discussion thread with the relevant work groups. Any maintainer may do this, not just the PR owner but make sure to check to not make a duplicate.

- All non-gamebreaking revert PRs *must* undergo a maintainer discussion before being created. If there is a PR that you would like to be reverted, please *create a thread in maint-reviews with the format REVERT-PRNumber and ping the relevant work group maintainers.* Discussions should reach a resolution within 48 hours, if discussions have stalled notify the Game Director or a PM.
**This does not apply for reverts made to the staging branch during the review period**, as there will be a discussion thread for the release.

- When closing a PR you must give a reason explaining why the PR is being closed, ideally this should include an alternative solution or approach. If a PR has been "dormant" it may be closed after attempting to contact the author with no response. A PR is considered "dormant" after 4 weeks of inactivity.

- When reviewing a PR use *constructive* language and avoid referring negatively to the author's ability. Strong but fair criticism of code/decisions are fine, personal criticisms are not.

- When reviewing code, don't assume that all contributors have your knowledge of the codebase. Giving a short explaination of how something works can be far more helpful than responding with jargon and pointing to the docs. *Sometimes a newer contributor may need more help, in that case direct them to #HowDoICode or the docs. But ideally you should try to give them a short explaination on what they need to do rather than just a "change this".
5 changes: 0 additions & 5 deletions src/en/wizden-staff/maintainer/wizards-den-review-policy.md

This file was deleted.

0 comments on commit 415a4c1

Please sign in to comment.