Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
58 lines (45 loc) · 2.52 KB

CONTRIBUTING.md

File metadata and controls

58 lines (45 loc) · 2.52 KB
Raw

Contributing to workspaces-host project

To see which files are managed by chezmoi run chezmoi managed. Never edit any managed without using chezmoi edit or opening the files in the chezmoi source directory. Use chezmoi edit <managed-file> --apply like chezmoi edit ~/.config/fish/config.fish --apply when you want to make quick edits to individual files and apply the changes immediately.

An easier way to modify these file is to use VS Code to edit and manage chezmoi templates and configurations using the code $(chezmoi source-path).

Be sure to follow the chezmoi workflows for editing configuration files and use chezmoi apply locally to do your testing.

Whenver possible, create chezmoi templates that generate configs (especially when secrets are involved, like in .gitconfig).

PRs are welcome. If you're making changes directly (without a PR), after updating and before pushing code, tag the release:

chezmoi cd
# <git commit ...>
git-semtag final && git push
# or git-semtag final -v "vN.N.N" && git push

Community dotfiles projects to learn from

Study these chezmoi-tagged repos:

They will have good ideas about how to properly create fully configurable home directories across all of our polyglot engineering stations.

Documenting workspaces-host project

A project is only as useful as its documentation so if you contribute to or modify code in this repo be sure to document it using this priority:

  • Follow guidance and conventions for Fish (e.g. use ~/.config/fish/* locations), chezmoi, brew, pkgx, direnv, etc. so that developers can easily understand your work
  • Add comments to scripts that explain not just what is being done but, more importantly, why
  • Whenever possible, explain concepts through visualizations using Draw.io (or D2/PlantUML/diagram-as-code utilities).
    • Instead of Visio or any other desktop-based tools please use the hediet.vscode-drawio VS code extension's *.drawio.svg and *.drawio.png capabilities. This allows you to edit the Draw.io files visually but an .svg or .png is automatically created for the repo (which can then be referenced/linked in Markdown like README.me).