First off, thank you for taking the time to contribute! We really appreciate it!
The following is a set of guidelines for contributing to NovelRT, which is hosted in the NovelRT Organization on GitHub. 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 NovelRT Contributor Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behaviour to [email protected] or message one of the maintainers on Discord.
Note: Please don't file an issue to ask a question. You'll get faster results by using the resources below.
We have an official message board on Github that you can utilize, or you can reach us on Discord where the community chimes in with helpful advice if you have questions.
When we make a decision in how we maintain the project and what we can or cannot support, we will typically announce this as part of a milestone on Github. If you have a question around what is being worked on by the NovelRT team, check to see if it is documented there. If it is not documented there, please open a new topic on Github Discussions or Discord and ask your question.
This section guides you through submitting a bug report for NovelRT. Following these guidelines helps maintainers and the community understand your report, reproduce the behaviour, and find related reports.
Before creating bug reports, please check this list as you might find out that you don't need to create one. We currently do not have a bug report template, so when you are creating a bug report, please include as many details as possible.
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.
- Most importantly, check if you can reproduce the problem in the latest version of NovelRT.
- Determine which repository the problem should be reported in. If it is specifically related to the NovelRT engine core, its samples, or its Interop layer, it should be reported here.
- 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 are tracked as GitHub issues. After you've determined which repository your bug is related to, create an issue on that repository following the steps below.
Explain the problem 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 configured NovelRT, e.g. which command exactly you used in the terminal, or how you built NovelRT otherwise. When listing steps, don't just say what you did, but explain how you did it. For example, if you built NovelRT using CMake, explain if you used Windows Command Prompt / Linux Terminal / Powershell, or a Developer Tools for VS window, and if so which version?
- 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 behaviour you observed after following the steps and point out what exactly is the problem with that behaviour.
- Explain which behaviour you expected to see instead and why.
- Include screenshots and/or animated GIFs if applicable which show you following the described steps and clearly demonstrate the problem.
- 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.
Provide more context by answering these questions:
- Did the problem start happening recently (e.g. after updating to the latest build of NovelRT) or was this always a problem?
- If the problem started happening recently, can you reproduce the problem in an older build of NovelRT? What's the most recent build/commit SHA in which the problem doesn't happen?
- Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
- What area of NovelRT is the problem occurring in? (e.g. Is it Input related? Is it related to Rendering or Windowing? etc)
Include details about your configuration and environment:
- Which build of NovelRT are you using?
- What's the name and version of the OS you're using?
- Was this pre-built? If not, what compiler was NovelRT built with?
- Are you using NovelRT with multiple monitors? If so, can you reproduce the problem when you use a single monitor?
- Which locale/region is your OS configured to use?
While we understand that not every issue may get resolved, we have a zero-tolerance policy for issues that fall under the following categories:
- Spam
- Hateful/discriminatory language
- Repeatedly reported non-issue
Please note that while we will do our best to filter out these types of submissions, they may still pop up from time to time. If you notice that one of these types of issues are opened in any of the NovelRT organisation's repositories, please e-mail [email protected] or message one of the maintainers in Discord. Furthermore, any attempt to open an issue that falls under the above categories may result in disciplinary action by the NovelRT team up to and including a ban from interacting with the NovelRT repository (and other related repositories within the NovelRT organisation). The NovelRT team also reserves the right to enforce disciplinary action for any reason that may be perceived to violate our Code of Conduct at any time.
This section guides you through submitting an enhancement suggestion for NovelRT, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
Before creating enhancement suggestions, please check this list as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please include as many details as possible.
- Check if there's already another repo which provides that enhancement. Note: NovelRT is still in its infancy, so this may not show much currently as we continue to enhance the engine core.
- Determine which repository the enhancement should be suggested in.
- Perform a cursory search to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
Enhancement suggestions are tracked as GitHub issues. After you've determined which repository your enhancement suggestion is related to, create an issue on that repository and provide the following information:
- Use a clear and descriptive title for the issue to identify the suggestion.
- Provide a step-by-step description of the suggested enhancement in as many details as possible.
- Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
- Describe the current behaviour and explain which behaviour you expected to see instead and why.
- Include screenshots and animated GIFs which help you demonstrate the steps or point out the part of NovelRT which the suggestion is related to, if possible. (We understand that sometimes code changes can't be shown with a screenshot)
- Explain why this enhancement would be useful to most NovelRT users as core functionality and isn't something that can or should be implemented as a community plugin.
- List some other game engines / examples where this enhancement exists (if applicable).
- Specify the name and version of the OS you're using.
Unsure where to begin contributing to NovelRT? You can start by looking through these good first issue and help wanted issues:
- Good first issues - issues which should only require a few lines of code, and a test or two.
- Help wanted issues - issues which should be a bit more involved than
good first issues.
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.
For instructions on how to get started with local development of NovelRT, see the following sections in the engine's README.
The process described here has several goals:
- Maintain NovelRT's quality
- Fix problems that are important to users
- Engage the community in working toward the best possible NovelRT
- Enable a sustainable system for NovelRT's maintainers to review contributions
Please follow these steps to have your contribution considered by the maintainers:
- Ensure that the title describes the overall enhancement/fix that is being provided.
- The description should summarise the changes being made, and should call out what area(s) of the engine is being affected.
- Follow the styleguide as provided by our
.clang-formatfile. (Our CI will assist you if you are unable to proactively do so, and will provide a git patch to fix most formatting issues, however this is not perfect and should not be guaranteed.) - Any changes in the contribution should follow UK English spelling to maintain consistency throughout the codebase (as it is what we use today). (We understand there may be slip-ups if this is not your custom however we ask that you try to catch these prior to submission.)
- The pull request that is opened should be linked to a corresponding issue.
- Once a pull request is opened, if you have not done so already you will be asked to sign our Contributor License Agreement (CLA).
- After you submit your pull request, verify that all status checks are passing
What if the status checks are failing?
If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.
While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted. Also, please note that under the circumstances listed below, a pull request may be rejected with/without further recourse by the NovelRT team for the following:
- Creating a pull request without an open issue (this is limited to contributors only as well as code/functionality changes indicated in any pull request - outside collaborators and maintainers are permitted within reason, and exceptions i.e. documentation-only changes may be permitted at maintainer discretion).
- Creating a pull request that purposefully breaks functionality / alters functionality in a negative manner
- Creating a pull request to introduce spam into the repository
Attempts to perform the actions called out above will result in disciplinary action by the NovelRT team up to and including a ban from interacting with the NovelRT repository (and other related repositories within the NovelRT organisation).
This section lists the labels we use to help us track and manage issues and pull requests. Most labels are used across all NovelRT repositories, but some are specific to novelrt/NovelRT.
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 across NovelRT that were approved by the team or perhaps open pull requests in novelrt/NovelRT which haven't been reviewed yet. 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 has 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 novelrt/NovelRT if you have suggestions for new labels, and if you notice some labels are missing on some repositories, then please open an issue on that repository.
This Contributing.md guide is adapted from the contribution guide provided by Atom under the MIT License.