github.com/df-mc/dragonfly@v0.9.13/.github/CONTRIBUTING.md (about)

     1  # Contributing to Dragonfly
     2  
     3  First, thank you for your interest in contributing to Dragonfly. :tada:
     4  
     5  The following is a set of guidelines for contributing to Dragonfly. These are guidelines and in
     6  general it is recommended to stick to them when contributing, but you should use your best
     7  judgement. Feel free to propose changes to this document in our Discord.
     8  
     9  ### Issues
    10  Issues are very welcome, both in the form of bug reports and feature requests. 
    11  
    12  When opening a bug report, please try to provide as much information as you can to reproduce the issue. When opening a 
    13  feature request, please be as clear as you can and provide concrete examples of how you think the proposed feature 
    14  should work. The more precise you are, the easier it is for someone to pick up your request. Don't be afraid to propose
    15  any ideas you might have, they may help people looking to pick up your feature request!
    16  
    17  As soon as a maintainer sees your issue and has enough information, your issue will be added to a milestone that
    18  indicates when we hope to have your issue resolved.
    19  
    20  ### Pull Requests
    21  In general, it is recommended to discuss any changes you would like to make in our Discord to
    22  before making changes, unless the change-set is otherwise small or limited to a specific part of
    23  the code base.
    24  
    25  When reviewing pull requests, we aim to reach the following goals with the code proposed:
    26  * Maintain the quality of the source code.
    27  * Stick to the standard formatting of Go (go fmt).
    28  * Provide a well-documented, simple and clean codebase.
    29  
    30  To make sure your pull request satisfies those points, we recommend you do the following before
    31  opening a pull request:
    32  * Run `go fmt` on any files you have changed to ensure the formatting is correct. Some IDEs have
    33    integration with this tool to run it automatically when committing. GoLand has a box that may be
    34    checked in the bottom-right corner when creating a commit.
    35  * Make sure to provide documentation for symbols where adequate. We generally follow the following
    36    conventions for documentation in pull requests:
    37    - Exported symbols (TypeName, FunctionName) should always have documentation over them, but if
    38      the function exists merely to satisfy an interface, the documentation may read 
    39      `// FunctionName ...` or be completely absent if the method has no functional behaviour.
    40    - Unexported symbols (typeName, functionName) _should_ have documentation, but doing so is not
    41      mandatory if the function is very simple and needs no clarification.
    42  * Make sure to use British English and proper punctuation throughout symbol names, variables and
    43    documentation.
    44  * Where possible, try to expose as few exported symbols (functions, types) as possible, unless 
    45    strictly necessary. This makes it easier for us to change code in the future and ensures that 
    46    users cannot use functions not suitable for the API.
    47  * In big functions it can become difficult to track the execution flow. Try to `return` as quickly
    48    possible in functions so that the main code flow is minimally indented and therefore easy to 
    49    track and understand.
    50  * In places where there are three or more sequential variable declarations, these should be grouped
    51    into a single `var ( )` block.
    52  * Try to be conservative with the usage of generics. While these are often useful, they can quickly
    53    pollute code if used in excess. Consider carefully if generics are needed, particularly for 
    54    exported types and functions. Don't hesitate on using them if they are able to clean up the code
    55    significantly.
    56  * We strive to have only completely functional features in the codebase. While we recognise that
    57    it is not always possible to provide full functionality for a feature in a single pull request,
    58    you should attempt to do so to the extent that you can. Specific smaller features part of the
    59    pull request that cannot be implemented yet should be marked with a `// TODO: ...` comment so
    60    that we can implement these when the required functionality is present.
    61  * When you open a PR, we assume you have tested your code and made sure it is working as intended.
    62    As a general recommendation, you should enable the Minecraft Content Log in the Profile settings
    63    so that it becomes obvious when invalid data is sent to the client.
    64    
    65  If you run into a problem or otherwise need help with your pull request, please feel free to reach
    66  out to us on Discord, so we can work towards a complete pull request together.