Skip to content

Latest commit

 

History

History
125 lines (100 loc) · 4.89 KB

CONTRIBUTING.md

File metadata and controls

125 lines (100 loc) · 4.89 KB
Raw

Contributing to Catspeak

Thank you for being interested in contributing to Catspeak. Please don't try to push directly to this repo, it wont work. Instead, fork this repo and make your changes there.

For more information, read the guidelines supplied by GitHub.

Contributing Guidelines

Issues

If you notice a problem with Catspeak, feel free to create an issue using the issue form. If you have multiple issues you want to report, please report them separately instead of as a monolithic task. Once you have created an issue, it may be updated with certain tags depending on its content.

If you would like to work on solving an issue, feel free to pick one and work on it. I wont assign issues to anyone.

Commit messages

This isn't necessarily very important, but please try and keep commit messages in the past tense and lower-case. Examples of commit messages include:

Style

Please try your best to follow the style of any surrounding code. Here are some brief tips:

  • Indentation uses 4 spaces, please do not use tabs.
  • Follow the K&R style for brackets.
  • Do not use multi-line comments.
  • Do not exceed 80 characters per line.
  • Do not use legacy delphi keywords and operators, examples include:
    • begin and end
    • The := assignment operator
    • The = and <> comparison operators
  • Ensure all statements end in a semi-colon.

I will still probably merge your PR if your code deviates from the style, but please try and keep the codebase consistent.

Testing

Running the developer project for Catspeak will also invoke the unit testing framework. You can find these under Testing/unit-tests in the GameMaker IDE.

If you add new logic, please add a relevant unit test.

Documentation

The documentation is generated completely automatically using a custom python script located in the root directory of this project. For this reason, please try to add good documentation to any new functions and methods.

However, if you don't want to write the documentation, please create an issue mentioning which items are missing documentation so that someone else can look into it.

Documentation Format

The general format of "doc comments" is similar to JSDoc, with some exceptions. Below is a template which should be followed for doc comments attached to functions and methods:

/// Description for `catspeak_example`.
///
/// @param {TypeName} arg1
///   A short description of what `arg1` is used for.
///
/// @example
///   Explain the following example:
///   ```
///   // add a GML example of how to use `catspeak_example`
///   ```
///
/// @return {TypeName}
///   Optional description of return type.
function catspeak_example(arg1) { ... }

All public functions should have explicit types for their arguments and return types. The only exception to this is if the return type is undefined, the @return tag does not need to be included.

You don't need to write documentation for internal functions.

There are also a handful of other JSDoc tags which can be used for better documentation. These are:

  • @ignore: Does not include the documented definition in the documentation.
  • @experimental: Includes a stab in the documentation definition warning that the feature may change or be removed randomly. It is not stablised.
  • @deprecated {version}: Includes a stab in the documentation definition warning that the feature has been deprecated since version, and should not be used anymore.
  • @throws {type}: Indicates that the function could potentially throw an exception of type.
  • @remark: Includes a note under the documentation description containing additional information.
  • @warning: Includes a note under the documentation description containing important information.
  • @example: Includes an example at the end of the definition documentation.

Building the Documentation

  1. (prerequisite) Make sure Mistletoe EBP in installed: 
    pip install mistletoe-ebp
    more info: https://mistletoe-ebp.readthedocs.io/en/latest/using/intro.html#installation
  2. Open a new terminal window.
  3. Navigate to the root directory of this repo, you should see a directory named docs-gen.
  4. Run 
    python ./docs-gen/build-docs.py

If you encounter no errors, then a new documentation page will be written to docs/<version>.