👍🎉 Thank you for contributing to the SEGS Project! 🎉👍
- Please be aware that SEGS is a Clean Room environment.
- We cannot keep our project at it's current legal status if we were to use leaked source code directly.
In short, everything made for SEGS is original and entirely independent from the leaked code.
The following is a set of guidelines for contributing to SEGS. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
I don't want to read this whole thing, I just have a question!!!
What should I know before I get started?
This project and everyone participating in it is governed by the SEGS Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to segs@github.com.
Note: Please don't file an issue to ask a question. You'll get faster results by reaching out to us on the SEGS Community Discord
Come and join us in #pocket-d channel for general chat or #troubleshooting for support.
Developers are welcome to join #development.
Click here to join SEGS Discord
SEGS is a large open source project with ambitious goals and a complex code base. Before contributing, please read through the entirety of this guide, as it contains important information that will help ensure that your contributions are accepted and successful.
Bugs, Enhancements, and Feature Requests are tracked as GitHub issues.
This section guides you through submitting an issue for SEGS. Following these guidelines helps maintainers and the community understand your report 📝, reproduce the behavior 💻, and find related reports 🔎.
Before creating issues, please check this list as you might find out that you don't need to create one. When you are creating an issue, please include as many details as possible. Fill out the required template, the information it asks for helps us resolve issues faster.
Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
- Check the debugging guide. You might be able to find the cause of the problem and fix things yourself. Most importantly, check if you can reproduce the problem in the latest version of SEGS.
- Check the FAQs on the wiki for a list of common questions and problems.
- Perform a cursory search to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one.
Bugs, Enhancements, and Feature Requests are tracked as GitHub issues. When creating an issue, please provide the following information by filling in the template.
Explain the problem or feature and include additional details to help maintainers reproduce the problem:
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as possible. For example, start by explaining how you started SEGS, e.g. which command exactly you used in the terminal, or how you started SEGS otherwise. When listing steps, don't just say what you did, but explain how you did it. For example, if you moved your character, explain if you used the mouse, or a keyboard to move, and if you used any powers or slash commands.
- Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
- Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
- Explain which behavior you expected to see instead and why.
- Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. If you use the keyboard while following the steps, record the GIF with the Keybinding Resolver shown. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
- If you're reporting that SEGS crashed, include a crash report with a stack trace from the operating system, and the
crash.logandoutput.logfiles from the SEGS directory. Include these reports in the issue in a code block, a file attachment, or put it in a gist and provide link to that gist. - If the problem is related to performance or memory, include a screenshot of your operating system's system monitor with your report, along with the
crash.logandoutput.log. - If the problem wasn't triggered by a specific action, describe what you were doing before the problem happened and share more information using the guidelines below.
- Explain why this enhancement would be useful to most SEGS users.
- Cite a source demonstrating this behavior in the original CoX Servers This is critical for showing intended behavior or output. Popular sources are https://ParagonWiki.com and https://youtube.com.
Provide more context by answering these questions:
- Can you reproduce the problem after restarting the server and client?
- Did the problem start happening recently (e.g. after updating to a new version of SEGS) or was this always a problem?
- If the problem started happening recently, can you reproduce the problem in an older version of SEGS? What's the most recent version in which the problem doesn't happen? You can download older versions of SEGS from the releases page.
- Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
- If the problem is related to working with files (e.g. opening and editing files), does the problem happen for all files and projects or only some? Does the problem happen only when working with local or remote files (e.g. on network drives), with files of a specific type (e.g. only JavaScript or Python files), with large files or files with very long lines, or with files in a specific encoding? Is there anything else special about the files you are using?
Include details about your configuration and environment:
- Which version of SEGS are you using? You can get the exact version by running
authserver -versionin your terminal. - What's the name and version of the OS you're using?
- Are you running SEGS in a virtual machine or using WINE? If so, which VM software are you using and which operating systems and versions are used for the host and the guest?
Unsure where to begin contributing to SEGS? You can start by looking through these good-first-issue and wishlist issues:
- Good First Issue - issues which should only require a small number of lines of code, and a test or two.
- Wishlist issues - issues which should be a bit more involved than
good-first-issueissues. These are issues that the SEGS core development team would love to implement or fix, but can't prioritize currently.
Both issue lists are sorted by total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have.
If you want to read about running SEGS, try the end-user README.
SEGS can be developed locally by cloning the git repo to your local machine. For instructions on how to do this, see the following sections in the development README:
- Fill in the required template
- Do not include issue numbers in the PR title
- Include screenshots and animated GIFs in your pull request whenever possible.
- Include thoughtfully-worded, well-structured commit messages. See the Coding Styleguide below.
- Document new code based on the Documentation Styleguide
- End all files with a newline
- Use the present tense ("Add feature" not "Added feature")
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- Limit the first line to 72 characters or less
- Reference issues and pull requests liberally after the first line
- When only changing documentation, include
[ci skip]in the commit description - If creating a new file, please add the standard SEGS copyright notice to the head of the file
- Consider starting the commit message with an applicable emoji:
- 🎨
:art:when improving the format/structure of the code - 🐎
:racehorse:when improving performance - 🚱
:non-potable_water:when plugging memory leaks - 📝
:memo:when writing docs - 🗃️
:card_index:when modifying the databases - 📜
:scroll:when modifying the LUA Scripts - 🐧
:penguin:when fixing something on Linux - 🍎
:apple:when fixing something on macOS - 🏁
:checkered_flag:when fixing something on Windows - 🐛
:bug:when fixing a bug - 🔥
:fire:when removing code or files - 💚
:green_heart:when fixing the CI build - ✅
:white_check_mark:when adding tests - 🔒
:lock:when dealing with security - ⬆️
:arrow_up:when upgrading dependencies - ⬇️
:arrow_down:when downgrading dependencies
- 🎨
-
Use spaces instead of tabs. ( Most editors allow one to set this up so 'tab' = 4 spaces )
-
The target brace style is:
namespace L
{
void exampleFunction(int params)
{
if (pred)
{
statement;
statement;
}
else
{
while (pred)
{
statement;
statement;
}
}
}
}- Lines should be limited to 120 characters; break longer lines. If an if statement has to be broken, use an extra tab on the continuation line e.g.
if (very very very very very very very very very very very very
very very long predicate)
{
statement; ...- In header files, reserve 2 tabs for the optional keywords virtual or static, and reserve enough tabs for the longest return type. i.e:
class X
{
public:
X();
~X();
virtual SomeType * function();
static void otherfunction();
};- Use descriptive function/member names (autocompletion is your friend). Also, consider naming your variable with the following formats for consistency and readability:
#DEFINE DEFINE_VAR // for DEFINE variables
auto m_member_var; // for member variables
auto s_file_scope_var; // for file scope variables
auto g_global_var; // for global variables.
auto throw_away; // for single-use limited scope, or throwaway varables.
QString m_underscore_separated_words; // underscore separate words
int s_dont_identify_type_in_name; // don't identify the variable type in the name. Type may change!
bool g_abbrev_are_ok_if_obvious; // abbreviations are ok, if they are obvious.
// real examples from source:
QString m_character_description;
bool m_is_flying;
uint32_t m_experience_points;
glm::vec3 m_pos; // with members m_pos.x, m_pos.y, m_pos.z;
float yaw;- Use spacing between binary mathematical, assignment, and ternary operators and their operands:
a = b + c;
a += x * y / z;
a = b ? c : d;- Doxygen documentation should be done in the implementation files (.cpp) and omitted from the headers. Proper and thorough documentation will enable others to better understand the intent of any code you contributed. Doxygen uses special comment syntax along with tags to accomplish this. For a definitive list of tags, please see Doxygen tags. We prefer Qt style (
/*!*/for multi-line and//!for single-line) comments. See below for various examples.
//! This class represents an Entity
class Entity
{
public:
// ...
private:
int id; //! contains the ID of the Entity
};
/*!
* @brief Clones an entity
* @param[in] src source Entity to copy from
* @param[out] dst destination Entity to copy to
* @returns true if copy was successful and false otherwise
*/
bool clone(Entity *src, Entity *dst)
{
// ...
if (!Entity)
return false;
else
return true;
}- Use Markdown whenever possible.
This section lists the labels we use to help us track and manage issues and pull requests. Open an issue to suggest new labels.
GitHub search makes it easy to use labels for finding groups of issues or pull requests you're interested in. For example, you might be interested in open issues which are labeled as bugs, but still need to be reliably reproduced or perhaps open pull requests which haven't been reviewed yet. To help you find issues and pull requests, each label is listed with search links for finding open items with that label. We encourage you to read about other search filters which will help you write more focused queries.
The labels are loosely grouped by their purpose, but it's not required that every issue have a label from every group or that an issue can't have more than one label from the same group.
Please open an issue on Segs/Segs if you have suggestions for new labels.
| Label Name | Search 🔎 | Description |
|---|---|---|
bug |
search | Confirmed bugs or reports that are very likely to be bugs. |
enhancement |
search | Feature requests. |
| Label Name | Search 🔎 | Description |
|---|---|---|
good-first-issue |
search | Issues that are great for beginners, or those new to the SEGS project. |
wishlist |
search | Issues that the SEGS core development team would love to implement or fix, but can't prioritize currently. |
network-layer-stability |
search | Related to SEGS network layer. |
| Label Name | Search 🔎 | Description |
|---|---|---|
work-in-progress |
search | Pull requests which are still being worked on, more changes will follow. |
needs-review |
search | Pull requests which need code review, and approval from maintainers or SEGS core team. |
under-review |
search | Pull requests being reviewed by maintainers or SEGS core team. |
requires-changes |
search | Pull requests which need to be updated based on review comments and then reviewed again. |
needs-testing |
search | Pull requests which need manual testing. |
This documentation was built off of the amazing work at https://github.com/atom/atom/blob/master/CONTRIBUTING.md