Skip to content
This repository has been archived by the owner on Jun 24, 2021. It is now read-only.

Latest commit

 

History

History
234 lines (177 loc) · 12.2 KB

CONTRIBUTING.md

File metadata and controls

234 lines (177 loc) · 12.2 KB
Raw

Contributing to GMS

First off, thanks for taking the time to contribute! 👍

The following is a set of guidelines for contributing to GMS project. These are mostly guidelines, not rules. Use your common sense and best judgment, and feel free to propose changes to this document in a pull request.

Table Of Contents

Code of Conduct

What should I know before I get started?

How Can I Contribute?

Code of Conduct

This project and everyone participating in it is governed by the GMS Code of Conduct. By participating in it, you are expected to keep this code. Please report any unacceptable behavior to lealceldeiro@gmail.com.

What should I know before I get started?

If you have extensively developed using Spring and preferably Spring Boot and Angular or simply want to make an improvement in any of the areas of the project that matches some of your expertise that's absolutely fine.

Frontend

Here is a list of some things (not a comprehensive list) worth knowing to develop in the frontend:

Backend

Here is a list of some things (not a comprehensive list) worth knowing to develop in the backend:

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check this list 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. 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.

Before Submitting A Bug Report

  • Perform a 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.

How Do I Submit A (Good) Bug Report?

Bugs are tracked as GitHub issues. Create an issue by providing the following information by filling in the template.

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 and animated GIFs which show you following the described steps and clearly demonstrate the problem. You can use this tool to record GIFs on macOS and Windows, and this tool on Linux.
  • If the problem wasn't triggered by a specific action, describe what you were doing before the problem happened.

Suggesting Enhancements

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. Fill in the template, including the steps that you imagine you would take if the feature you're requesting existed.

Before Submitting An Enhancement Suggestion

  • Determine which part of the project the enhancement should be suggested in (brackend, frontend).
  • Perform a 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.

How Do I Submit A (Good) Enhancement Suggestion?

Enhancement suggestions are tracked as GitHub issues. After you've determined which part of the project your enhancement suggestion is related to, create an 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 and animated GIFs which help you demonstrate the steps or point out the part of the project which the suggestion is related to. You can use this tool to record GIFs on macOS and Windows, and this tool on Linux.
  • Explain why this enhancement would be useful.
  • Specify which version of GMS you're using.
  • Specify the name and version of the OS where the server is running on if the enhancement you're requesting corresponds to the backend.
  • Specify the name and version of the browser you're using if the enhancement you're requesting corresponds to the frontend.

Pull Requests

The process described here aims to:

  • Maintain GMS code quality.
  • Fix problems that are important to users.

Please follow these steps to have your contribution considered by the maintainers:

  1. Follow all instructions in the template.
  2. Follow the styleguides.
  3. 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 not related to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated.

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.

Styleguides

Git Commit Messages

  • Start the commit messages with one of the following options, followed by the issue number (if apply) and a short description of what is this commit about:
    • Server: if the changes are in the server side
    • Client: if the changes are in the client side
    • Documentation: if the changes are related to the project documentation, such as modifying reamde, licence, etc. files
    • Integration: if the changes are in files related to CI/CD, GitHub related, IDE configurations, etc. files, such as a .travis.yml, .gitignore, .github/**, etc.
  • Use the present tense ("Add feature" not "Added feature").
  • Use the imperative mood ("Expand card..." not "Expands card...").
  • Limit the first line to 72 characters or less.
  • Reference issues and pull requests liberally after the first line.

JavaScript/TypeScript Styleguide

All JavaScript and Typescript must adhere to JavaScript Standard Style (although some rules have been modified for this project) and the Angular Style Guide:

  • Prefer the object spread operator ({...anotherObj}) to Object.assign().

  • Inline exports with expressions whenever possible.

    // Use this:
export default class ClassName {

}

// Instead of:
class ClassName {

}
export default ClassName

  • If you need to have some mocked function with arguments and variables (which will not be used) you should name them following this regex: [iI]gnored|[uU]nused.

  • Use snake case only (when needed) for those model properties that need to match backend API responses, otherwise use always camel case.

  • Prefer the dot notation over the square-bracket notation. The last should be used as a last resort when doing unit tests and you need to access some private properties of the unit being tested.

  • Empty constructors are allowed.

  • Always finalize a line with a semicolon.

  • A space after a semicolon is required if it is not the last statement in the line.

  • There should not be a space before a function parenthesis.

  • Limit every line to 120 characters max.

  • Place requires/imports in the following order:

    • Angular Modules
    • Third party modules/libraries (add blank line to separate them from the Angular module)
    • Local Modules (add blank line to separate them from the Angular module or the third party modules if any)

  • Include thoughtfully-worded, well-structured Jasmine specs next to each component, service, etc.

  • Treat describe as a noun or situation.

  • Treat it as a statement about state or how an operation changes state.

Java Styleguide

All Java code must adhere the Java Language Specification, the Sun Code Conventions, the Javadoc guidelines, the JDK Api documentation, and some best practices using common sense:

  • Limit every line to 120 characters max.
  • An argument may have the same name of a local variable in constructors and setter methods as long as inside them this is used to make the difference between the local field and the argument.
  • Avoid platform-dependent code.
  • Create the specs for every class that needs it under src/test/java/com/gms/<path-to-class-as-it-is-in-src-main-java-com-gms>.
  • Always aim to create unitary tests and all the e2e tests considered necessary.
  • For endpoints, always provide e2e tests where the documentation is generated using Asciidoctor. Also, create the needed resources in the folder src/main/asciidoc with the correspondent description regarding to the created/updated change and link them to the resources created by the tests.

Note: we use checkstyle to make easier to follow these conventions.

Documentation Styleguide

  • Always documents every field, property and method in both sides: client and server.
  • Use Markdown for frontend and the proper jsdoc style for backend.