Contributing

Thank you for contributing. Contributions are always welcome, no matter how large or small.

Guidelines

As a contributor, here are the guidelines you should follow:

Code of conduct
How can I contribute?
Using the issue tracker
Submitting a Pull Request
Coding rules
Working with code

We also recommend to read How to Contribute to Open Source.

Code of conduct

Please read and follow our code of conduct.

How can I contribute?

Improve documentation

Consider helping us to improve our documentation by finding documentation issues that need help, and by submitting pull requests for corrections, clarifications, more examples, new features, etc.

Please follow the Documentation guidelines.

Give feedback on issues

Some issues are created without information requested in the Bug report guideline. Help making them easier to resolve by adding any relevant information.

Issues with the type: discussion label are meant to discuss the implementation of new features. Participating in the discussion is a good opportunity to get involved and influence the future.

Fix bugs and implement features

Confirmed bug and ready to implement features are marked with the help label. Post a comment on an issue to indicate you would like to work on it, and to request help from the maintainer(s) and the community.

Using the issue tracker

The issue tracker is the channel for bug reports, features requests and submitting pull requests only. Please use the Support and Get help sections for support, troubleshooting and questions.

Before opening an Issue or a Pull Request, please use the GitHub issue search to make the bug or feature request hasn't been already reported or fixed.

Bug report

A good bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as possible in your report and fill the information requested in the Bug Report.

Feature request

Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible and fill the information requested in the Agile User Story form/template.

Submitting a Pull Request

Good pull requests whether patches, improvements or new features are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.

Please ask first before embarking on any significant pull request (e.g. implementing features, refactoring code), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.

If you never created a pull request before, then learn how to submit a pull request (great tutorial).

Here is a summary of the steps to follow:

Set up the workspace
If you cloned a while ago, get the latest changes from upstream and update dependencies.
Create a new topic branch (off the main project development branch) to contain your feature, change, or fix; git checkout -b <topic-branch-name>
Make your code changes, following the Coding rules
Push your topic branch up to your fork; git push origin <topic-branch-name>
Open a Pull Request with a clear title and description.

Tips:

Create your branch from main.
Ensure your git commit messages follow the required format.
Ensure your scripts are well-formed, well-documented and object-oriented.
Ensure your scripts are stateless and can be reused by all.
Update your branch, and resolve any conflicts, before making pull request.
Fill in the required template.
Do not include issue numbers in the PR title.
Include screenshots and animated GIFs in your pull request whenever possible.
Follow the style guide applicable to the language or task.
Include thoughtfully-worded, well-structured tests/specs. See the Tests/Specs Style Guide.
Document new code based on the Documentation Style Guide.
End all files with a newline.

Coding rules

Commit message guidelines
Documentation
Lint
Source Code
Tests/Specs

Working with code

Configure SSH authentication
Set up the workspace
Running tests

Configure SSH authentication for containerized workspace

The following steps enable the containerized workspace to authenticate when retrieving private repositories from GitHub. This also ensures a universal experience for all contributors, without disrupting anyone's existing keys.

If you've already created a "shared RSA key", you can skip this section.

Generate an RSA key:

ssh-keygen -t rsa -b 4096 -C "{username}@users.noreply.github.com"

When prompted, provide file path ~/.ssh/id_rsa_shared.

Enter file in which to save the key (~/.ssh/id_rsa): ~/.ssh/id_rsa_shared

Do not set a passphrase, just click enter twice.

Enter passphrase (empty for no passphrase):
Enter same passphrase again:

This will create 2 files, a private-key and its public-key companion.
```
~/.ssh/id_rsa_shared
~/.ssh/id_rsa_shared.pub
```

Create a ~/.ssh/config_shared file and put the following text in it.

Host github.com
  IgnoreUnknown UseKeychain
  AddKeysToAgent yes
  IdentityFile /root/.ssh/id_rsa_shared

Copy the contents of the public-key to your clipboard.
```
cat ~/.ssh/id_rsa_shared.pub
```
Add the id_rsa_shared.pub key to your GitHub Account.

Set up the workspace

Clone the repo into the current directory

git clone https://github.com/seantrane/dotfiles.git dotfiles && cd dotfiles

Set up the Dev Container...

Dev Containers ensure consistency across different environments. Follow these steps to set up a Dev Container in Visual Studio Code:

Install Docker on your machine.
Install Visual Studio Code on your machine.

Install the Remote - Containers and Remote Development Extension Pack extensions for VS Code.

code --install-extension ms-vscode-remote.remote-containers
code --install-extension ms-vscode-remote.vscode-remote-extensionpack

Based on your machine's operating system follow the below instructions.

...for Ubuntu/Linux/Mac based machines

Ensure Docker Desktop is up and running in your local machine.
Open the project in VS Code from the root of the repository.
When prompted, click on the blue "Reopen in Container" button in the bottom-right corner of VS Code or Press Ctrl+Shift+P to open the Command Palette click on "Dev Containers: Reopen in Container".

...for Windows based machines

Install and setup WSL2 on your windows machine.

If you have already configured SSH authentication and Cloned the repository in windows then, copy id_rsa_shared, id_rsa_shared.pub and config_shared files from Windows to .ssh folder in Linux using the below commands.

# Copy .ssh folder to Linux
cp -r /mnt/c/Users/<username>/.ssh ~/.

# Get into .ssh folder
cd .ssh

# Set necessary permissions to id_rsa_shared
sudo chmod 600 id_rsa_shared

# Set necessary permissions to id_rsa_shared.pub
sudo chmod 600 id_rsa_shared.pub

Clone the repository in WSL2
Open the project in VS Code from the root of the repository in WSL2.
When prompted, click on the blue "Reopen in Container" button in the bottom-right corner of VS Code or Press Ctrl+Shift+P to open the Command Palette click on "Dev Containers: Reopen in Container".

Wait for the Dev Container to finish building, before contributing.

Working with CSV files

CSV files are tricky to edit/save properly, depending on the software used to open them. Microsoft Excel is capable of opening/editing/saving the file correctly. Some apps will corrupt the data/formatting, resulting in a failing pull request.

Running tests

Static Analysis with MegaLinter

# Run linters on entire repository
./run megalinter

# Run linters only on changed files
./run megalinter -e 'VALIDATE_ALL_CODEBASE=false'

# Run linters and apply formatter fixes on changed files
./run megalinter -e 'APPLY_FIXES=all' -e 'VALIDATE_ALL_CODEBASE=false'

# Run a specific version of megalinter
export MEGALINTER_VERSION="v7"; ./run megalinter

File Structure

~/.dotfiles/
├─ bin/                       * Anything in `bin/` will get added to your `$PATH`
│  │                            and be made available everywhere.
│  ├─ {binary}                * Any shell script you wish.
│  :
│
├─ functions/                 * Anything in `functions/` will be loaded in environment.
│  ├─ {function}              * Shell function (with filename identical to function name)
│  :
│
├─ {topic}/                   * Directory with files pertaining to a specific topic or application.
│  ├─ aliases.{,ba,z}sh       * Any file named `aliases.{,ba,z}sh` is loaded into your environment.
│  ├─ completion.{ba,z}sh     * Any file named `completion.{ba,z}sh` is loaded last
│  │                            and is expected to setup autocomplete.
│  ├─ path.{,ba,z}sh          * Any file named `path.{,ba,z}sh` is loaded first
│  │                            and is expected to setup `$PATH` or similar.
│  ├─ *.{,ba,z}sh             * Any files ending in `.{,ba,z}sh` get loaded into your environment.
│  ├─ *.symlink               * Any files ending in `*.symlink` get symlinked into your `$HOME`.
│  :                            For example; `npmrc.symlink` would be symlinked to `~/.npmrc`
│                               This is so you can keep all of those versioned in your dotfiles
│                               but still keep those autoloaded files in your home directory.
│                               These get symlinked in when you run `script/bootstrap`.
│
└─ cli                        * Command-line interface

Dotfiles File Structure Explained

~/.dotfiles/                  * dotfiles directory
│
├─ bash/                      * Bash config, env, profile, rc, etc.
├─ bin/                       * Binary scripts (loaded into shell PATH)
├─ brew/                      * Homebrew config, installers, inits
├─ functions/                 * Shell functions (loaded into shell PATH)
├─ git/                       * Git config
├─ macos/                     * macOS config, defaults, prefs, aliases, etc.
├─ script/                    * Shell scripts for installing, maintaining dotfiles
├─ shell/                     * Shell config (common settings for all shells)
├─ system/                    * System/OS config, aliases, paths, etc.
├─ user/                      * User config, aliases, local rc's
├─ zsh/                       * Zsh config, env, profile, rc, etc.
│
├─ cli                        * CI/CD CLI
└─ run                        * "run" helper script

Zsh configuration process

Legend:

icon	description
👉	symlinked file
⭐️	very important file
👀👤	user file (if exists)

/etc/zshenv
~/.zshenv 👉 ~/.dotfiles/zsh/zshenv.symlink ⭐️
- ~/.zprofile 👉 ~/.dotfiles/zsh/zprofile.symlink
  - ~/.profile 👀👤
- ~/.dotfiles/brew/paths.sh
- ~/.env 👉 ~/.dotfiles/system/env.symlink
  - ~/.dotfiles/shell/response.sh ⭐️
  - ~/.dotfiles/shell/paths.sh ⭐️
    - ~/.dotfiles/**/path.{sh,zsh} ⭐️
    - ~/.path 👀👤
  - ~/.dotfiles/shell/exports.sh ⭐️
  - ~/.dotfiles/shell/functions.sh
    - ~/.rvm/scripts/rvm
    - ~/.functions 👀👤
  - ~/.dotfiles/functions/* ⭐️
/etc/zprofile 🛑
~/.zprofile 👉 ~/.dotfiles/zsh/zprofile.symlink ⭐️
- ~/.profile 👀👤
/etc/zshrc
~/.zshrc 👉 ~/.dotfiles/zsh/zshrc.symlink ⭐️
- ~/.zprezto/init.zsh
- ~/.localrc 👀👤
- ~/.dotfiles/**/aliases.{sh,zsh} ⭐️
- ~/.aliases 👀👤
- /etc/zsh_command_not_found
- ~/.dotfiles/**/completion.zsh ⭐️
- ~/z/z.sh || /opt/homebrew/etc/profile.d/z.sh
/etc/zlogin
~/.zlogin 👉 ~/.dotfiles/zsh/zlogin.symlink
/etc/zlogout
~/.zlogout 👉 ~/.dotfiles/zsh/zlogout.symlink

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CONTRIBUTING.md

CONTRIBUTING.md

Contributing

Table of Contents

Guidelines

Code of conduct

How can I contribute?

Improve documentation

Give feedback on issues

Fix bugs and implement features

Using the issue tracker

Bug report

Feature request

Submitting a Pull Request

Coding rules

Working with code

Configure SSH authentication for containerized workspace

Set up the workspace

Clone the repo into the current directory

Set up the Dev Container...

...for Ubuntu/Linux/Mac based machines

...for Windows based machines

Working with CSV files

Running tests

Static Analysis with MegaLinter

File Structure

Dotfiles File Structure Explained

Zsh configuration process

Happy coding!

Files

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing

Table of Contents

Guidelines

Code of conduct

How can I contribute?

Improve documentation

Give feedback on issues

Fix bugs and implement features

Using the issue tracker

Bug report

Feature request

Submitting a Pull Request

Coding rules

Working with code

Configure SSH authentication for containerized workspace

Set up the workspace

Clone the repo into the current directory

Set up the Dev Container...

...for Ubuntu/Linux/Mac based machines

...for Windows based machines

Working with CSV files

Running tests

Static Analysis with MegaLinter

File Structure

Dotfiles File Structure Explained

Zsh configuration process

Happy coding!