Skip to content

Go version Python version GitHub License GitHub commit activity GitHub Actions Workflow Status GitHub Issues GitHub Pull Requests Documentation Website

Readme

Welcome to Vimle! This project is a suite of utilities written in Golang, designed to simplify various development tasks.

Features

Vimle includes the following utilities (planned utilities are in bold):

  • gurli → A cli tool to generate files using templates and data files;
  • malma → A CLI tool to manage project metadata and versioning;
  • poang → A CLI tool to manage service ports in containers (Docker, Monad, Kubernetes), acting as a database of service ports;
  • riconto → A CLI tool to create PDF or EPUB eBooks from Markdown sources;
  • bolmen → Yet another dotfile management tool;
  • depot → A CLI tool to manage a local directory containing multiple Git repositories.

Also there are some utilities present in the pkg directory, that are of general purpose, by package:

  • commondirs → Provides the GetCommonDirectories() function to retrieve common system and user directories in POSIX or macOS environments;
  • questions → Offers functions for user input, including boolean, character, decimal, hidden text, integer, and text inputs;
  • utils → Includes functions for converting strings to various integer types and vice versa.

Installing

Vimle is currently in alpha. Installation instructions will be provided in future releases.

Development

Required Tools

To contribute to Vimle, ensure you have the following tools installed:

  • mise → A tool similar to asdf, which installs other required tools easily for the current user and project;
  • qlty → A tool to run several linters at once.

Mise is configured to install the following tools when you run mise install or enter the project directory:

  • go (1.24.2) → The Go language tools, as Vimle is written in Go;
  • python (3.12<= x > 4.0) → The Python interpreter, used in the build and maintenance scripts;
  • rust (stable) → Required for installing tools that use Cargo;
  • golangci-lint (2.1.2) → A linter for Go code;
  • task (3.42.1) → A task runner similar to Make;
  • goconvey (>=1.8.1) → A test framework for Go with a web-based UI;
  • go-enum → A tool for generating Go code to mimic enumerations;
  • lefthook (>=1.11.11) → A Git hook management tool;
  • cocogitto → A Rust tool for managing conventional commits;
  • pdm → A tool for creating local Python virtual environments, so that the build and maintainance scripts are runned in it.

Mise provides the following environment variables:

  • $ROOT → Path to the project root;
  • $CMD_ROOT → Path to the cmd directory ($ROOT/cmd);
  • $SCRIPT_ROOT → Path to the script directory ($ROOT/script);
  • $INTERNAL_ROOT → Path to the internal directory ($ROOT/internal);
  • $COMMON_ROOT → Path to the internal/common directory ($ROOT/internal/common);
  • $PKG_ROOT → Path to the pkg directory ($ROOT/pkg);
  • $DOCS_ROOT → Path to the docs directory ($ROOT/docs).

Development Guidelines

This project follows semantic versioning. Each individual tool has its own version, and the project as a whole is versioned globally. For example, project version X.Y.Z may include tool versions a.b.c, d.e.f, etc.

Commit Messages

Commit messages adhere to the conventional commit standards. Each message should be a single line in the following format:

type(scope): message
  • Type: One of feat (new features), fix (bug fixes), merge (pull request merges), or chore (refactoring, documentation updates);
  • Scope: The affected area, such as a utility name, pkg, or script.

The message should be written using a present verb, so that it goes well when combined with the sentence:

If I get this commit, I will ...

Example of ok messages:

  • add feature X to utility A → Becoming If I get this commit, I will add feature X to utility A;
  • fix error Y in utility A → Becoming If I get this commit, I will fix error Y in utility A;

Examples of invalid messages:

  • added feature X → Would become If I get this commit, I will added feature X which does not make sense;
  • fixed error Y and Z → Would become If I get this commit, I will fixed error Y and Z which does not make sense.

Pull Requests

To contribute, follow these steps:

  1. Create an issue to discuss your problem or feature;
  2. Reference the issue in your pull request description;
  3. GPG-sign all commits in your pull request;
  4. Ensure all lint checks, tests, and builds pass;
  5. Verify that all pull request checks pass.

Code of Conduct

This project adheres to the guidelines outlined in CODE_OF_CONDUCT.md. Please ensure respectful and constructive communication.

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Authors

The primary author of this project is carddamom.