Skip to content

Conversation

@Princess-Cheeseballs
Copy link
Member

Description

Did some organizing/cleanup of the docs repo to add descriptions for the different types of Maintainers and added Documaintainer as a new type of maintainer. Also moved doc review policy to it's own file rather than it being tacked on to the end of content review procedure.

Why?

Documents do not get the maintenance that they deserve, this has been a persistent problem for years. They're also something that we do not need a full content maintainer to maintain, and are of a specialization different from code review. This is a low hanging fruit for a task we can split off into a specialized new staff role.

In addition, the docs repo is extremely important. All staff changes, policy changes, and such MUST go through the docs repo. Therefore the more competent hands we can have maintaining the docs repo, the easier it will be to make important policy changes, add new types of specialized staff which allows us to lift a lot of the burden off of our currently small maintainer team.

Copy link
Contributor

@juliangiebel juliangiebel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need to add the new page to SUMMARY.md

@Princess-Cheeseballs
Copy link
Member Author

You need to add the new page to SUMMARY.md

I swear I did fug

@Princess-Cheeseballs
Copy link
Member Author

Ok it's working now

Copy link
Contributor

@RemFexxel RemFexxel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small grammar and text improvements.

# Maintainer

This section contains information on Maintainer and PR-Review Policies, **as it pertains to Wizards Den servers, hosted by Space Wizards.** These policies do not apply to other servers, and may be waived in exceptional circumstances.
This section contains information on Maintainer and PR-Review Policies, **as it pertains to Wizards Den servers, hosted by Space Wizards.** These policies do not apply to other servers, and may be waived in exceptional circumstances.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This section contains information on Maintainer and PR-Review Policies, **as it pertains to Wizards Den servers, hosted by Space Wizards.** These policies do not apply to other servers, and may be waived in exceptional circumstances.
This section contains information on Maintainer and PR-Review Policies, **as it pertains to Wizards Den servers, hosted by Space Wizards.** These policies do not apply to other servers and may be waived in exceptional circumstances.


## Maintainer

A maintainer is a member of staff who is given authority and trust in reviewing and merging PRs. All maintainers regardless of specialization are expected to follow Maintainer Policy.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A maintainer is a member of staff who is given authority and trust in reviewing and merging PRs. All maintainers regardless of specialization are expected to follow Maintainer Policy.
A maintainer is a member of staff who is given authority and trust to review and merge PRs. All maintainers, regardless of specialization, are expected to follow the Maintainer Policy.


### SS14 Maintainer

A SS14 Maintainer maintains the content side of Space Station 14. This includes the docs repo, and content repo.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A SS14 Maintainer maintains the content side of Space Station 14. This includes the docs repo, and content repo.
A SS14 Maintainer maintains the content side of Space Station 14. This includes the docs repo and the content repo.


### Documaintainer

A Documaintainer is a SS14 Maintainer who only has Maintainer powers for the Docs Repo. Within the docs repo they have the same power and authority as an SS14 Maintainer.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A Documaintainer is a SS14 Maintainer who only has Maintainer powers for the Docs Repo. Within the docs repo they have the same power and authority as an SS14 Maintainer.
A Documaintainer is an SS14 maintainer who only has maintainer powers for the Docs Repo. Within the docs repo, they have the same power and authority as an SS14 maintainer.


### Head Mapper

A Head Mapper is a SS14 Maintainer who has exclusive power over content PRs with map changes and additions. These maintainers are expected to ensure mapping standards and their approval is required for any PRs which make mapping changes.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A Head Mapper is a SS14 Maintainer who has exclusive power over content PRs with map changes and additions. These maintainers are expected to ensure mapping standards and their approval is required for any PRs which make mapping changes.
A Head Mapper is an SS14 Maintainer who has exclusive power over content PRs with map changes and additions. These maintainers are expected to ensure mapping standards are met, and their approval is required for any PRs that make mapping changes.


### UI Lead

A UI Lead is a SS14 Maintainer who has exclusive power over content PRs with UI changes and additions. These maintainers are expected to ensure the game retains usable, aesthetically pleasing UIs which fit the game's art style.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A UI Lead is a SS14 Maintainer who has exclusive power over content PRs with UI changes and additions. These maintainers are expected to ensure the game retains usable, aesthetically pleasing UIs which fit the game's art style.
A UI Lead is an SS14 Maintainer who has exclusive power over content PRs with UI changes and additions. These maintainers are expected to ensure the game retains usable, aesthetically pleasing UIs which fit the game's art style.


### Robust Toolbox maintainer

A Robust Toolbox Maintainer is a Maintainer for the game's engine Robust Toolbox. These are the only Maintainers who have merge powers for the engine.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A Robust Toolbox Maintainer is a Maintainer for the game's engine Robust Toolbox. These are the only Maintainers who have merge powers for the engine.
A Robust Toolbox maintainer is a maintainer for the game's engine, Robust Toolbox. These are the only Maintainers who have merge powers for the engine.


A UI Lead is a SS14 Maintainer who has exclusive power over content PRs with UI changes and additions. These maintainers are expected to ensure the game retains usable, aesthetically pleasing UIs which fit the game's art style.

### Robust Toolbox maintainer
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Robust Toolbox maintainer
### Robust Toolbox Maintainer

Comment on lines +3 to +24
The Docs repo has a different review policy compared to the Content repository.
Since the Docs repo can be pushed to directly by maintainers, is mostly text-based, can be easily reverted/changed, and does not affect forks, most docs pull requests can be handled by a single maintainer.

### Pushing to the Docs Repo
Maintainers have direct push access to the Docs repo and are encouraged to use it to update any outdated information, whether it's technical documentation, amending a design document, or just fixing grammar.

### PR Reviews
PRs that update instructional or reference documentation (including but not limited to setup guides, style guides, system documentation) require only a single approval before it can be merged.
Likewise, only a single maintainer needs to express concern to close it.

Note that this does not apply to changes to internal procedure or other modifications that require voting or group deliberation according to relevant policy.

#### Design Documents
Major PRs that introduce or change a design document should require at least two maintainer approvals.
If the addition is large enough, a maintainer can call a vote on the design document; however, this should be done only when the scope of the pull request warrants it.

Major game features usually follow the below dynamic:
1. A contributor creates a preliminary design document demonstrating what they would like to add, offering a high-level overview of how it fits into the game.
2. Maintainers discuss the document in an informal discussion. If most agree, the document is marked with `S: Doc Approved`, and the contributor can start work on the actual feature. As the feature is developed, the document is updated if necessary.
3. Once the content-side implementation is ready to be merged, both the design document and the content pull request are merged in tandem.

The intention behind this is to ensure that contributors do not waste time implementing a feature that may not fit well into Upstream's intended gameplay.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The Docs repo has a different review policy compared to the Content repository.
Since the Docs repo can be pushed to directly by maintainers, is mostly text-based, can be easily reverted/changed, and does not affect forks, most docs pull requests can be handled by a single maintainer.
### Pushing to the Docs Repo
Maintainers have direct push access to the Docs repo and are encouraged to use it to update any outdated information, whether it's technical documentation, amending a design document, or just fixing grammar.
### PR Reviews
PRs that update instructional or reference documentation (including but not limited to setup guides, style guides, system documentation) require only a single approval before it can be merged.
Likewise, only a single maintainer needs to express concern to close it.
Note that this does not apply to changes to internal procedure or other modifications that require voting or group deliberation according to relevant policy.
#### Design Documents
Major PRs that introduce or change a design document should require at least two maintainer approvals.
If the addition is large enough, a maintainer can call a vote on the design document; however, this should be done only when the scope of the pull request warrants it.
Major game features usually follow the below dynamic:
1. A contributor creates a preliminary design document demonstrating what they would like to add, offering a high-level overview of how it fits into the game.
2. Maintainers discuss the document in an informal discussion. If most agree, the document is marked with `S: Doc Approved`, and the contributor can start work on the actual feature. As the feature is developed, the document is updated if necessary.
3. Once the content-side implementation is ready to be merged, both the design document and the content pull request are merged in tandem.
The intention behind this is to ensure that contributors do not waste time implementing a feature that may not fit well into Upstream's intended gameplay.
The Docs repo has a different review policy compared to the Content repository.
Since the Docs repo can be pushed to directly by maintainers, is mostly text-based, can be easily reverted/changed, and does not affect forks, most docs pull requests can be handled by a single maintainer.
### Pushing to the Docs Repo
Maintainers have direct push access to the Docs repo and are encouraged to use it to update any outdated information, whether it's technical documentation, amending a design document, or just fixing grammar.
### PR Reviews
PRs that update instructional or reference documentation (including, but not limited to, setup guides, style guides, and system documentation) require only a single approval before they can be merged.
Likewise, only a single maintainer needs to express concern to close it.
Note that this does not apply to changes to internal procedure or other modifications that require voting or group deliberation according to relevant policy.
#### Design Documents
Major PRs that introduce or change a design document should require at least two maintainer approvals.
If the addition is large enough, a maintainer can call a vote on the design document; however, this should be done only when the scope of the pull request warrants it.
Major game features usually follow the following dynamic:
1. A contributor creates a preliminary design document demonstrating what they would like to add, offering a high-level overview of how it fits into the game.
2. Maintainers discuss the document in an informal discussion. If most agree, the document is marked with `S: Doc Approved`, and the contributor can start work on the actual feature. As the feature is developed, the document is updated if necessary.
3. Once the content-side implementation is ready to be merged, both the design document and the content pull request are merged in tandem.
The intention is to ensure that contributors do not waste time implementing a feature that may not fit well with Upstream's intended gameplay.

- **Three Maintainers must *sign-off*** (Approval is required, reviewing is recommended but optional) on a hotfix PR for it to be merged.
- The Hotfix procedure only applies to PRs being merged straight to "stable" or "staging". **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/review-procedure.md) in addition to any requirements listed here.
- All Hotfixes must adhere to the normal [PR Review Procedure](../maintainer/content-review-procedure.md) in addition to any requirements listed here.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- All Hotfixes must adhere to the normal [PR Review Procedure](../maintainer/content-review-procedure.md) in addition to any requirements listed here.
- All Hotfixes must adhere to the normal [PR review procedure](../maintainer/content-review-procedure.md) in addition to any requirements listed here.

If we're using "PR review procedure" for what I assume should apply to all pages, then this should be continued.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants