Skip to content

Latest commit

 

History

History
201 lines (145 loc) · 7 KB

CONTRIBUTING.md

File metadata and controls

201 lines (145 loc) · 7 KB

Contributing

Table of Contents

How to contribute

You can contribute to the project in several ways. You can either report a bug, request a feature, or discuss the current state of the project. To do so, you can create an issue or a pull request.

Creating an issue

Before contributing, make sure to check if there's an existing issue for the task you want to work on.

If not, you can create an issue with the following rules:

  • Name the issue with a short description
  • Describe the issue with a description
  • Add labels to the issue

Creating a pull request

Before contributing, make sure to check if there's an existing pull request for the task you want to work on.

When you do a pull request, you have to use the following rules:

  • Name the pull request with the same convention as commit convention.
  • Describe the pull request with a description of what you did.
  • Add the core team as reviewers.
  • You have to squash your commits to one commit with the number of the issue and the short description. (It should be automatic)

If the pull request is related to an issue, you have to add the issue number in the description.

If the pull request is related to a graphical feature, you have to add a screenshot of the feature in the description or a link to a video or a link to a repository with the feature.

To meet the requirements of the project, the pull request has to be approved by the core team and have tests if applicable. (Look at Testing Policies for more details)

Project structure

Currently, the project contains 1 main part compossed of tools for E2 projects, located in ./src.

Commit naming convention

Commit structure

<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │       │
  │       └─⫸ Commit Scope
  │
  └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test|chore

The <type> and <summary> fields are mandatory, the (<scope>) field is optional.

Type

Must be one of the following:

  • build : Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • ci : Changes to our CI configuration files and scripts (examples: CircleCi, SauceLabs)
  • docs : Documentation only changes
  • feat : A new feature
  • fix : A bug fix
  • perf : A code change that improves performance
  • refactor : A code change that neither fixes a bug nor adds a feature
  • test : Adding missing tests or correcting existing tests
  • chore : Chore changes (update .gitignore, dependencies, etc.)

Scope

The scope should be the name of the file, the directory or the feature involved in the commit.

Here are some examples:

  • gitignore
  • main
  • action
  • readme

Summary

Use the summary field to provide a succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • don't capitalize the first letter
  • no dot (.) at the end

Important

We a CI that check if your commit message is correct. If it's not, you will have to change it before pushing your code.

Coding style

To have a consistent codebase, we follow a coding style. This coding style is enforced by clang-format. You can find the configuration file in the root of the project.

Local coding style

  1. Download clang-format from here or from Github
  2. Add the clang-format executable to your PATH

Apply the coding style

For bash users, you can use the following command to apply the coding style to the project:

find . -iname '*.hpp' -o -iname '*.cpp' | xargs clang-format -i

For Windows users, you can use the following command to apply the coding style to the project:

Get-ChildItem -Recurse -Include *.cpp, *.hpp | ForEach-Object { clang-format -i $_.FullName }

Automatic coding style

We also have a CI that will update the code style automatically. So don't forget to pull the latest changes before pushing your code.

Namespace convention

As we are using C++, we have to use namespaces. The namespace should define precisely what the file is about. For example, if you have a .hpp that contains all the math functions, you should put it in the math namespace like:

namespace ES::Plugin::Math::3D {
  // Your code here
}

and in the .cpp file, you should put it in the same namespace as:

ReturnType ES::Plugin::Math::3D::FunctionName() {
  // Your code here
}

Warning

Don't put global namespace in the .cpp file like:

namespace ES::Plugin::Math::3D {
  ReturnType FunctionName() {
    // Your code here
  }
}

Header

Each .hpp must contain an header guard of this form:

/**************************************************************************
 * [name of the project] [version of the project]
 *
 * [name of the project] is a software package, part of the Engine².
 *
 * This file is part of the [name of the project] project that is under GPL-3.0 License.
 * Copyright © 2024 by @EngineSquared, All rights reserved.
 *
 * [name of the project] is a free software: you can redistribute it and/or modify
 * it under the terms of the GPL-3.0 License as published by the
 * Free Software Foundation. See the GPL-3.0 License for more details.
 *
 * @file [name of the file]
 * @brief [short description of the file]
 *
 * [long description of the file]
 *
 * @author @[your name]
 * @version [version of the file]
 * @date [date of the file]
 **************************************************************************/

You can find an example of a header guard in the vk-wrapper/src/queueFamilies/QueueFamilies.hpp plugin file.

File and folder naming

Source and header files should be named with PascalCase convention like FooBar.hpp or FooBar.cpp.

Folder names should be named with dash-case convention like ./foo-bar/.

Code Documentation

To have a consistent codebase, we follow a documentation style. This documentation style is enforced by Doxygen. You can find the configuration file in the root of the project.