Thank you for taking the time to contribute to Gorgon.
The following is a set of guidelines for contributing. These are mostly guidelines, not rules. So, use your best judgment, and feel free to propose changes to this document in a pull request.
This project and everyone participating in it is governed by the Gorgon Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].
This section guides you through submitting a bug report for Gorgon. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
Before creating bug reports, please check the issues tab as you might find out that you don't need to create one. 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.
Bugs are tracked as GitHub issues.
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.
- 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 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.
This section guides you through submitting an enhancement suggestion for Gorgon, 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.
Enhancement suggestions are tracked as GitHub issues. Create a new issue 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 behavior and explain which behavior you expected to see instead and why.
- Include screenshots (if possible) which help you demonstrate the steps or point out the part of Gorgon which the suggestion is related to.
- Explain why this enhancement would be useful to most Gorgon users and isn't something that can or should be implemented separately.
- Specify which version of Gorgon you're using.
You can start by looking through these beginner and help-wanted issues:
beginner- issues which should only require a few lines of code, and a test or two.help-wanted- issues which should be a bit more involved thanbeginnerissues.
Both issue lists are sorted by total number of comments.
The process described here has several goals:
- Fix problems that are important to users
- Enable a sustainable system for Gorgon's maintainers to review contributions
Please follow these steps to have your contribution considered by the maintainers:
- Follow the Style information.
- 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.
- Limit the first line to 72 characters or less
- Reference issues and pull requests liberally after the first line
Code will be subject to code review before pushing into the root branch(es).
All C# code must adhere to the best practices as outlined by Microsoft. Deviations may be acceptable upon review by a maintainer on a case by case basis.
Additionally, code must be formatted, as closely as possible, in the style present throughout the library code base. This means:
- Use Tabs - not spaces.
- Only use #region blocks to organize your code. Do NOT use them to hide code, or separate access modifiers (e.g. do not use #region Private members, #region Protected members, etc...).
What regions are acceptable?
#region Constants. // Constants go here. #endregion #region Classes. // Inner classes go here. These should always be private. #endregion #region ValueTypes. // Inner value types go here (struct). These should always be private. #endregion #region Events. // Event declarations go here. #endregion #region Properties. // Properties go here. #endregion #region Methods. // Methods go here. #endregion #region Constructor. // Constructors go here. // Finalizers too (change "Constructor" to "Constructor/Finalizer") #endregion
- Try to adhere as closely to SOLID principles as possible.
- When building user interfaces, try to use MVVM (or something approaching my bastardization of it - see the Editor code).
- Try to use small, concise methods. Do not write massive methods that take more than 1.5 pages to get through.
- Try to keep method/constructor parameters down to 4-6 parameters. Sometimes this is not possible, so this will depend on context.
When writing the documentation for your code, please try to be concise and try to convey your intent clearly.
- Always comment your code. You don't need to write War & Peace, but something to describe your thinking is required.
- Comments for events, methods, properties, classes, structs, and non-private variables must use XML commenting. Private variables can use standard commenting.
- Ensure comments are up to date. Don't make a function that returns the sum of two numbers and have a comment that describes drawing a pixel on the screen.
If your code does something strange to get around a problem, please write comments either in the body, or section explaining why the code is written the way it is. Many of the libraries (including .NET itself) in use in Gorgon have quirks, it's good to know where there are.
Gorgon has been in evolving and developed over years, and as such, styles and methodologies have changed over time. This means that the code isn't always compliant with the guidelines in this document. Do not take that to mean that these guidelines are optional, they are not. This is very much a case of do as I say, not as I once did when I was young and dumb.
This section lists the labels we use to help us track and manage issues and pull requests.
GitHub search makes it easy to use labels for finding groups of issues or pull requests you're interested in.
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.