Skip to main content Skip to docs navigation
Check
View on GitHub

Contribute

Contribute to the development of dotfiles-cli using the documentation, build scripts and tests.

On this page

Tooling setup

  • bash is required for running/debugging the executable
  • Node.js is optional for managing the documentation site
Docs site is using npm scripts to build the documentation and compile source files. The package.json houses these scripts which used for various docs development actions.

Guidelines

  • PRs need to have a clear description of the problem they are solving
  • PRs should be small
  • Code without tests is not accepted, PRs must not reduce tests coverage
  • Contributions must not add additional dependencies
  • Before creating a PR, make sure your code is well formatted, abstractions are named properly and design is simple
  • In case your contribution can’t comply with any of the above please start a GitHub issue for discussion

How to Contribute?

  1. Fork this repository
  2. Create a PR on the forked repository
  3. Send a pull request to the upstream repository

Development Scripts

The makefile within this repository contains numerous tasks used for project development. Run make to see all the available scripts in your terminal.

Task Description
create_tarball Create a tarball from local repository
install_from_respository Install a local dotfiles CLI from this repository
uninstall Uninstall a local dotfiles CLI
release_version_create Create release tag in GitHub with version from resources/version.txt
release_version_delete Enter a tag to delete its attached release tag from GitHub
calculate_sha_by_commit_hash Enter a commit to get its SHA hash
calculate_sha_by_tag Enter a tag to get its SHA hash
serve_docs_site Run a local docs site
serve_docs_site_lan Run a local docs site (open for LAN)
test Run tests suite
fmt Format shell scripts using shfmt bash style (https://github.com/mvdan/sh)
Note that some of those development actions require write access to the repository.

Testing Locally

Running tests locally allows you to have short validation cycles instead of waiting for the PR status to complete.

How to run a test suite?

  1. Clone the dotfiles-cli repository
  2. Run make test to run the tests suite

Documentation Scripts

The /docs-site/package.json includes numerous tasks for developing the documentation site. Run npm run to see all the available npm scripts in your terminal. Primary tasks include:

Task Description
npm run docs-build Cleans the Hugo destination directory for a fresh serve
npm run docs-serve Builds and runs the documentation locally
npm run docs-serve-lan Builds and runs the documentation locally, make it available on home network
(for testing views on mobile phones)

Local documentation

Running the documentation locally requires the use of Hugo, which gets installed via the hugo-bin npm package. Hugo is a blazingly fast and quite extensible static site generator. Here’s how to get it started:

  • Run through the tooling setup above to install all dependencies
  • Navigate to /docs-site directory and run npm install to install local dependencies listed in package.json

Checking site on browser:

Checking site on mobile (via LAN):

  • From the repository root folder run make serve_docs_site_lan

  • Open http://192.168.xx.xx:9001 in your mobile browser

    Make sure to update the --baseURL IP address on the package.json file under docs-serve-lan task.

Learn more about using Hugo by reading its documentation.