Skip to content

Contribution Guide

Code of Conduct

  • Be kind to others ;
  • Critic code not people.

👍 Work inside a Docker

Info

We use docker to isolate from our working environment.

Specify the FISH_VERSION you want, and the CMD executed by the container:

make build-pure-on FISH_VERSION=4.0.2
make dev-pure-on FISH_VERSION=4.0.2 CMD="fishtape tests/*.test.fish"

Working with NixOS

We have targets for NixOS called nix-build-pure-on and nix-dev-pure-on:

❯ make build-pure-on-nix dev-pure-on-nix FISH_VERSION=4.0.2

Code Conventions

Be Fishy

Use the idiomatic test instead of [ brackets (as recommended by the documentation).

Be Explicit

Use long form options, e.g. set --local, as they are more explicit over cryptic 1-letter form.

Naming Public Item

Namespace your item with the prefix pure_.

  • Variable: pure_my_variable
  • Function: pure_my_public_function
  • Filename: pure_my_public_file.fish
  • Test file: pure_my_public_file.test.fish

Naming Private Item

Namespace your item with the prefix _pure_ (begin with a single underscore).

  • Variable: _pure_my_variable
  • Function: _pure_my_private_function
  • Filename: _pure_my_private_file.fish
  • Test file: _pure_my_private_file.test.fish

Local and Tools

No need to use namespace when your variable variable is declare locally (set --local) or your file/test file is related to tooling (installer.fish, testing package managers install).

  • Filename: my_tool.fish
  • Test file: my_tool.test.fish

Global Variable

Color's Variables

Base colors should follow $pure_color_<meaning> pattern (cf. bootstrap naming).

Example

$pure_color_info     # cyan
$pure_color_success  # green
$pure_color_warning  # yellow
$pure_color_danger   # red
$pure_color_light
$pure_color_dark
$pure_color_muted    # gray

Feature's Variables

Each feature should have a dedicated variables to allow customization. Feature's variables (flag, symbol, color) should use $pure_<type>_<feature> naming pattern:

Role Name pattern
flag $pure_<verb>_<feature>
color $pure_color_<feature>
symbol $pure_symbol_<feature>

Example

$pure_enable_git_status

$pure_symbol_git_unpushed_commits

$pure_color_git_unpulled_commits

Feature Flag's Variable

Name should follow $pure_<verb>_<feature> pattern, where:

  • verb describe the action triggered by the feature (i.e. separate, begin, show, etc.) ;
  • feature descibre the what of the feature (i.e. prompt_on_error, with_current_directory, git_status, etc.). Value should be a boolean.

Example

$pure_begin_prompt_with_current_directory = true

$pure_enable_git_async = false

Avoid abbreviation

Use complete word over abbreviation.

Example

$pure_threshold_command_duration

Posting on social media

There is a manual workflow to post on social media.

Releasing

Release process is automated in the pipeline with the following steps.

Info

We follow semver, release is manage in the pipeline

Test

We run the test workflow on:

  • Pull Request changing
  • any **.fish ;
  • and workflow (*.yml) files ;
  • on master branch changing
  • **.fish files with the exception conf.d/pure.fish, as we have dedicated mechanism to manage versions bump ;
  • and workflow (*.yml) files

Versioning

Success

Commit messages must follow conventional commits convention.

Versioning is done automatically based on commit messages and triggered only on master branch.

Details:

  1. We compute the project's next version using a GitHub Action ;
  2. Then update $pure_version value in ./conf.d/pure.fish ;
  3. Finally commit and push the change to the repo.

Adding new tag

The add-version-tag.yml pipeline is triggered only for master when ./conf.d/pure.fish is changed and add a tagged based on $pure_version.