Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
183 lines (126 loc) · 6.38 KB

CONTRIBUTING.md

File metadata and controls

183 lines (126 loc) · 6.38 KB

Contributing to trdl

trdl is an Open Source project, and we are thrilled to develop and improve it in collaboration with the community.

Before you start

For any significant change, open the issue first (or comment on an existing one) to discuss with the maintainers on what to do and how. When the solution is agreed upon, you can proceed with implementation and open a pull request.

For small changes, such as few lines bugfixes or documentation improvements, feel free to open a pull request directly.

For easy first issues, check the good first issue tag.

You can also check the existing issues, discussion threads, and documentation — there may already be a discussion or solution on your topic. If not, choose the appropriate way to address the issue on the new issue form.

Contributing code

  1. Fork the project.

  2. Clone the project:

    git clone https://github.com/[GITHUB_USERNAME]/trdl

  3. Prepare an environment. To build and run trdl locally, you'll need to at least have the following installed:

    • Git 2.18.0+

    • Go 1.23

      Important: Go Toolchain Configuration

      To prevent unwanted modifications to the go.mod file (specifically the automatic addition of a toolchain directive), you must set the following environment variable:

      export GOTOOLCHAIN=local

      We recommend adding this setting to your shell profile (e.g., .bashrc, .zshrc, or equivalent) to make it persistent across sessions:

      echo 'export GOTOOLCHAIN=local' >> ~/.bashrc
source ~/.bashrc

      This configuration ensures Go uses only the locally installed version of the tools instead of automatically selecting and potentially adding a toolchain version to go.mod, preventing unintended changes to the file.

    • Docker

    • ginkgo (testing framework required to run tests)

    • go-task (build tool to run common workflows)

      • Before using Taskfile, set the environment variable: 
        export TASK_X_REMOTE_TASKFILES=1
        (Add this to your shell configuration file, e.g., .bashrc or .zshrc, for persistence.)
      • To skip confirmation prompts when running tasks, use the --yes flag: 
        task --yes taskname
        Useful for automation or when you're sure the task should run without manual confirmation.

      To install dependencies, use the following task:

    • task deps:install

  4. Make your changes.

  5. Build all trdl binaries:

    task build:dev:all

    You can also check out all available tasks with task -l.

  6. Format and lint your code:

    task format lint

    Note: The task format and task lint will run Prettier inside a container.

  7. Testing:

    1. Setup testing environment: 
      task server:setup:dev-environment
    2. Run tests: 
      task server:test:unit
task e2e:test:e2e
    3. Cleanup testing environment: 
      task server:dev:cleanup
    4. Do manual testing (if needed).

  8. Commit your changes. See Conventions for the commit message format. The commit must be signed off (--signoff) as an acknowledgment of the DCO.

  9. Push and open a pull request.

Conventions

Commit message

Each commit message consists of a header and a body. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>

Type

Must be one of the following:

  • feat: new features or capabilities that enhance the user's experience.
  • fix: bug fixes that enhance the user's experience.
  • refactor: a code changes that neither fixes a bug nor adds a feature.
  • docs: updates or improvements to documentation.
  • test: additions or corrections to tests.
  • chore: updates that don't fit into other types.

Scope

Scope indicates the area of the project affected by the changes. The scope can consist of a top-level scope, which broadly categorizes the changes, and can optionally include nested scopes that provide further detail.

Supported scopes are the following:

# The end-user functionalities, aiming to streamline and optimize user experiences.
- actions
- release
- client
- server
- docs

# Maintaining, improving code quality and development workflow.
- ci
- release
- dev
- deps
- taskfile
- e2e

Subject

The subject contains 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

Body

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.

Branch name

Each branch name consists of a type, scope, and a short-description:

<type>/<scope>/<short-description>

When naming branches, only the top-level scope should be used. Multiple or nested scopes are not allowed in branch names, ensuring that each branch is clearly associated with a broad area of the project.

Short description

A concise, hyphen-separated phrase in kebab-case that clearly describes the main focus of the branch.

Pull request name

Each pull request title should clearly reflect the changes introduced, adhering to the header format of a commit message, typically mirroring the main commit's text in the PR.

Code style

See CODESTYLE.md.

Improving the documentation

The documentation is created using Jekyll and is located in ./docs. Please refer to the docs LOCALDEV.md for information about the development process.