This is the contribution guide for Paradise Station. These guidelines apply to both new issues and new pull requests. If you are making a pull request, please refer to the Pull request section, and if you are making an issue report, please refer to the Issue Report section.
If you comment on an active pull request or issue report, make sure your comment is concise and to the point. Comments on issue reports or pull requests should be relevant and friendly, not attacks on the author or adages about something minimally relevant. If you believe an issue report is not a "bug", please point out specifically and concisely your reasoning in a comment on the issue itself.
Comments on Pull Requests and Issues should remain relevant to the subject in question and not derail discussions.
Under no circumstances are users to be attacked for their ideas or contributions. All participants on a given PR or issue are expected to be civil. Failure to do so will result in disciplinary action.
For more details, see the Code of Conduct.
The Issues section is not a place to request features, or ask for things to be changed because you think they should be that way. The Issues section is specifically for reporting bugs in the code.
Issue reports should be as detailed as possible, and if applicable, should include instructions on how to reproduce the bug.
Players are welcome to participate in the development of this fork and submit their own pull requests. If the work you are submitting is a new feature, or affects balance, it is strongly recommended you get approval/traction for it from our forums before starting the actual development.
It is expected that all code contributors read and understand the Guide to Quality PRs.
Keep your pull requests atomic. Each pull request should strive to address one primary goal, and should not include fixes or changes that aren't related to the main purpose of the pull request. Unrelated changes should be applied in new pull requests. In case of mapping PRs that add features - consult a member of the development team on whether it would be appropriate to split up the PR to add the feature to multiple maps individually.
Document and explain your pull requests thoroughly. Failure to do so will delay a PR as we question why changes were made. This is especially important if you're porting a PR from another codebase (i.e. /tg/station) and divert from the original. Explaining with single comment on why you've made changes will help us review the PR faster and understand your decision making process.
Any pull request must have a changelog. This is to allow us to know when a PR is deployed on the live server. Inline changelogs are supported through the format described here.
Pull requests should not have any merge commits except in the case of fixing
merge conflicts for an existing pull request. New pull requests should not have
any merge commits. Use git rebase or git reset to update your branches, not
git pull.
Please explain why you are submitting the pull request, and how you think your change will be beneficial to the game. Failure to do so will be grounds for rejecting the PR.
If your pull request is not finished, make sure it is at least testable in a live environment. Pull requests that do not at least meet this requirement may be closed at maintainer discretion. You may request a maintainer reopen the pull request when you're ready, or make a new one.
While we have no issue helping contributors (and especially new contributors) bring reasonably sized contributions up to standards via the pull request review process, larger contributions are expected to pass a higher bar of completeness and code quality before you open a pull request. Maintainers may close such pull requests that are deemed to be substantially flawed. You should take some time to discuss with maintainers or other contributors on how to improve the changes.
By ticking or leaving ticked the option "Allow edits and access to secrets by maintainers", either when making a PR or at any time thereafter, you give permission for repository maintainers to push changes to your branch without explicit permission. Repository maintainers will avoid doing this unless necessary, and generally should only use it to apply a merge upstream/master, rebuild TGUI, deconflict maps, or other minor changes required shortly before a PR is to be merged. More extensive changes such as force-pushes to your branch require explicit permission from the PR author each time such a change needs to be made.
- The tags able to be used in the changelog are:
add/soundadd/imageadd,del/sounddel/imagedel,tweak,fix,wip,spellcheck, andexperiment. - Without specifying a name it will default to using your GitHub name. Some examples include:
:cl:
add: The ability to change the color of wires
del: Deleted depreciated wire merging now handled in parent
fix: Moving wires now follows the user input instead of moving the stack
/:cl: :cl: UsernameHere
spellcheck: Fixes some misspelled words under Using Changelog
/:cl:Status of your pull request will be communicated via PR labels. This includes:
-
Status: Awaiting type assignment- This will be displayed when your PR is awaiting an internal type assignment (for Fix, Balance, Tweak, etc) -
Status: Awaiting approval- This will be displayed if your PR is waiting for approval from the specific party, be it Balance or Design. Fixes & Refactors should never have this label -
Status: Awaiting review- This will be displayed when your PR has passed the design vote and is now waiting for someone in the review team to approve it -
Status: Awaiting merge- Your PR is done and is waiting for a maintainer to merge itNote: Your PR may be delayed if it is pending testmerge or in the mapping queue
All PRs which modify maps are expected to follow all of our mapping requirements.
Some parts of Paradise are written in Rust for performance or reliability reasons:
- Our atmos engine, MILLA, is in the
rust/src/milla/directory. - The
mapmaniplibrary, an Aurora Station module used for automating DMM modification, is in therust/src/mapmaniplibrary.
The Rust parts of our codebase are compiled into a single library, separate from the rest of the code. If you're on Windows, you get a pre-built copy by default. If you're on Linux, you built one already to run the server.
If you make changes to the Rust library, you'll want to rebuild. This will be
very similar to rust-g. The only difference is that you run cargo from the
rust/ directory, and don't need to specify --all-features (though it doesn't
hurt).
The server will automatically detect that you have a local build, and use that over the default Windows one.
When you're ready to make a PR, please DO NOT modify rustlibs.dll or
tools/ci/librustlibs_ci.so. Leave "Allow edits and access to secrets by
maintainers" enabled, and post a comment on your PR saying !build_rust. A bot
will automatically build them for you and update your branch.
-
Bloated code may be necessary to add a certain feature, which means there has to be a judgement over whether the feature is worth having or not. You can help make this decision easier by making sure your code is modular.
-
You are expected to help maintain the code that you add, meaning that if there is a problem then you are likely to be approached in order to fix any issues, runtimes, or bugs.
-
If you used regex to replace code during development of your code, post the regex in your PR for the benefit of future developers and downstream users.
-
All new var/proc names should use the American English spelling of words. This is for consistency with BYOND.
-
All mentions of the company "Nanotrasen" should be written as such - 'Nanotrasen'. Use of CamelCase (NanoTrasen) is no longer proper.
-
If you are making a PR that adds a config option to change existing behaviour, said config option must default to as close to as current behaviour as possible.
There are three roles on the GitHub:
- Headcoder
- Maintainer
- Review Team
Each role inherits the lower role's responsibilities (IE: Headcoders are also maintainers, and maintainers are also part of the review team)
Headcoders are the overarching "administrators" of the repository. People
included in this role are:
Maintainers have write access to the repository and can merge your
PRs. People included in this role are:
Review Team members are people who are denoted as having reviews which can
affect mergeability status. People included in this role are:
Full information on the GitHub contribution workflow & policy can be found at https://www.paradisestation.org/dev/policy/.