Contribution Guidelines
It's awesome that you're considering contributing to Socially Distant's development with your time. However, to keep development moving smoothly for everybody, there are a few things you need to keep in mind. This page demonstrates how to properly contribute to the game, as well as what's expected from all contributions.
Sign into GitLab with your acidic light community account
Socially Distant's source code is available on our GitLab server. You'll need an account on it in order to submit contributions.
You can either create an acidic light community account through GitLab itself, or sign in using Discord, GitHub, or Patreon.
Set up SSH or HTTPS access for Git
In order to push changes to GitLab, you'll need to be able to sign in through Git with your acidic light community account. The easiest way to do this is with Git Credential Manager, but you will still need either an SSH key or a Personal Access Token.
Get a Personal Access Token (for HTTPS)
Once signed into GitLab, click your profile picture then go to Preferences.
On the left sidebar, click Access Tokens.
On the main area, under the *Personal Access Tokens8 section, click the "Add new token" button on the far right.
In the form that appears, give your new token a name and expiry date. Under Token scopes, check "api".
Click Create personal access token, then copy the token. When Git Credential Manager asks for a token, this is what you give it. Do not share it with anyone else, not even a plushie.
Add an SSH key (for SSH)
If you prefer to authenticate using an SSH key, you must add your public key to your account.
Once signed into GitLab, click your profile picture then go to Preferences.
On the left, select SSH Keys.
In the form that appears, paste your public key into the Key field. Give the key a name and expiration date, and make sure its usage type is Authentication and Signing.
Click Add key, and then you're all set. Make sure that you clone repositories over SSH instead of HTTPS, like so:
git clone git@gitlab.acidiclight.dev:/sociallydistant/sociallydistant.git
Fork the game
Make sure you fork the game on GitLab before trying to push changes. Once you have, add it as an origin to your clone of the game.
# HTTPS
git remote add fork https://gitlab.acidiclight.dev/YOU/sociallydistant.git
# SSH
git remote add fork git@gitlab.acidiclight.dev:/YOU/sociallydistant.git
Then, check out a branch to work in.
git checkout -b my-cool-feature
Push the branch to your fork:
git push -u fork my-cool-feature
If the push was successful, you will get prompted to create a merge request. Feel free to do this now, as a way of showing what you intend to change, if you'd like.
The legal stuff
You should keep in mind that Socially Distant is a commercial game, even though it is also an open-source project. Therefore, it is extremely important we ensure that we are legally allowed to incorporate your work in the game, while also protecting your own rights to the content being contributed. For this reason, Socially Distant contributions are protected with the Developer Certificate of Origin.
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
Socially Distant's own code is licensed under the MIT License.
When submitting a merge request to Socially Distant, an automated build pipeline will run to check the work you've submitted. In order for the pipeline to succeed, you must acknowledge your understanding of the Developer Certificate of Origin, and must certify that your work is submitted under a license compatible with that of Socially Distant's own code. To do this, follow these instructions:
- Set your Git configuration
Your Git user name and email must match the display name and email of your acidic light community account, otherwise the DCO check won't pass.
git config --global user.name "Your Name"
git config --global user.email "youremail@example.com"
- Sign-off your commits
Use the -s flag to sign-off when making a commit.
git commit -s
This will generate a Signed-off-by: Your Name <your email> text based on your Git config, and this is what the DCO check will look for.
Communication etiquette
When contributing to Socially Distant, please be respectful of the community etiquette. Intentional mis-use of the community's GitLab server will result in a ban, and any associated repositories will be removed for storage reasons.
Follow community rules
The GitLab is governed under the same rules as the Discord server.
- Respect all members at all times. Harassment and bullying will not be tolerated.
- Do not spam messages, images, emoji or pings.
- NSFW (explicit or suggestive) content is not permitted or tolerated under any circumstances.
- Posting invite links to other Discord servers is not allowed unless otherwise cleared by a moderator or administrator.
- Offensive or controversial content (racism, homophobia, targeted hate, etc.) are not allowed.
- Discuss controversial topics in a civil manner. There are people with differing views on these subjects and all views should be respected when objectively reasonable. Moderators are permitted to forcibly de-escalate or stop debates if necessary.
- Do not share harmful links or malware. Do not share binary executable files.
- Sharing/leaking of Patreon-exclusive content is not allowed.
Keep things on-topic.
Discussions on the GitLab should be related to the game's development, and nothing else. Please do not use the GitLab to ask for help playing the game, or for general programming help. Do not use the GitLab as a platform for advertisement of other communities or projects, unless directly related to Socially Distant.
Know how to human.
Contributions may be subject to a manual code review in certain cases. Any and all feedback given by a maintainer about your work is a criticism of the work itself, not you as a person. You are expected to treat others the same.
Development follows Ritchie's lead.
If you feel there is something you can bring to the table to help Socially Distant's development, then you should. However, please do not feel discouraged if and when a contribution doesn't get accepted. The only reason a contribution doesn't get accepted would be that it breaks the game or that it doesn't align with the game's direction. Sometimes, interesting-sounding mechanics might not actually fit with the rest of the game and that's okay.
Ritchie Frodomar is the BDFL (benevolent dictator for life) of Socially Distant. This means the game's development will always directly follow Ritchie's plans.
If ever there is a time where an issue cannot be resolved unanimously or a project decision needs to be made, Ritchie's decision is the final decision on behalf of the project. Unless explicitly stated otherwise, Ritchie's decisions are absolutely final. Endless circular debating isn't productive and just annoys people.
Any decisions made related to Socially Distant's development are made in the best interest of the game itself, in the hopes that people will enjoy playing it when it is finished.
Write good commit messages
When a new version of the game is released, or when a devlog is published, we always include a list of all changes made to the game since the last update. This change list is always generated based on Git commit logs. Therefore, you should make sure you write well-formatted commit messages.
All commits should be small and incremental, to ease the burden of code reviews. With that in mind, commit messages should generally answer these questions:
- What are you trying to do? Write a short but descriptive one-sentence title explaining what you are actually trying to do with these changes. You may be adding a new feature, fixing a bug, documenting something, adding an asset to the game, or anything in between. Just remember to keep it short and sweet, this is the part of the commit that actually shows in changelogs.
- What are you changing? Your commit body should be a more technical description of what your changes are actually doing.
- Is this change related to an issue? If so, link it. People watching that issue will get notified.
Commit messages should also be written in the imperative mood.
Examples of good commit messages
Add support for confirmation dialogs in System Settings
Add an API for showing a confirmation dialog when the user
changes a given setting in System Settings. The API allows
the setting to provide a warning message to show when the
user changes the setting.
If the user dismisses the dialog, the setting change is
reverted. Otherwise, the change is committed. The setting
field can also specify a callback to perform when the
change is confirmed, like restarting the game.
Fixes issue #47
Signed-off-by: Ritchie Frodomar <alkalinethunder@gmail.com>
Document various layout widgets
Add API documentation for the Stack Panel,
Flex Panel, Wrap Panel, and Scroll View.
Signed-off-by: Human Person <iamnotarobot@human.ai>
Fix memory leak when closing lots of terminals
Fixes an issue where closing a Terminal via the close
button on the tab doesn't kill the underlying shell process,
leading to a memory leak as a result of the shell never
exiting.
Signed-off-by: Hari Mann <hari-mann@notareal.email>
Write human code
Human code is code that can be easily understood by a human being with objectively reasonable programming skill. Your code should be easily understood by yourself and by the team, and by a person unfamiliar with the codebase, That is always the priority. We do not subscribe to any specific design pattern or programming paradigm, as this is a large codebase and the correct way to approach a problem depends on the problem.
Here are some general tips to ensure your code is human.
- Use good naming: Pick names that aren't confusing, do not use abbreviations, and do not use magic numbers.
- Write comments when the code isn't obvious: If it isn't immediately obvious what your code is doing or why it needs to do what it's doing, write a comment above it to describe that. It's okay to forget, but you may still need to describe the code later in a review.
- Don't write comments when the code is obvious: If your code is well-written, its intentions will be obvious. Lots of comments clutters the screen, so don't over-explain your code.
- Functioning code is good code: It may be tempting to write abstractions or find ways to avoid repeating yourself - but this is a waste of time. Prioritize making your code actually work before trying to make it look pretty. If an abstraction is needed, it'll grow organically.
- Functioning code is fast: Do not get hung up on performance. If your code doesn't actually show up as a red flag in a performance profiler, you don't need to optimize it. Well-written code is easy to optimize later when that's actually needed.
For even more info about code style, read the style guide.
Please document your API!
Please remember to document any new API you add to the game, and feel free to fill in missing API documentation if you see it. It's important for others to be able to learn their way around the code.
Socially Distant uses the docfx project to generate this online manual. This includes the documentation for the game's API. Please use C#'s XML documentation strings when documenting public API.
Ideally, all code should be as self-documenting as possible. However, any public APIs need to be explicitly documented so that other developers know why and how to use the API.
Lastly, have fun.
Never feel pressured to contribute to the game, and if you need help, ask!