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=3.3.1
make dev-pure-on FISH_VERSION=3.3.1 CMD="fishtape tests/*.test.fish"

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

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.