Skip to content

Latest commit

 

History

History
111 lines (67 loc) · 5.54 KB

CONTRIBUTING.md

File metadata and controls

111 lines (67 loc) · 5.54 KB
Raw

Contributors' Guidelines

A few basic guidelines for contributing to the Sublime PML project.

Table of Contents

Issues and Discussions

The repository offers two different areas for interacting with its maintainers: Issues and Discussions.

Issues are intended for any communications directly relating to the repository development, such as:

  • Bug reports.
  • New feature requests.
  • Anything that directly translates into a coding task, with no further ado.

Discussions, on the other hand, can be used to discuss anything relating to the Sublime PML package, from ideas, proposal to comparison with other packages and general talk. Unlike Issues, Discussions threads allow nested posts, i.e. commenting on the main post or other comments in a tree-structured manner, and in some cases (depending on the setting of each category) also pose questions and then select the correct answer from the various replies.

Submitting Code and Contents

Contributions to the repository should be submitted via Pull Requests (PRs) on the dev branch.

Code Styles Convention

This repository adopts EditorConfig to enforce consistent code styles in the repository contents and across different editors and IDEs.

If you're using an editor or IDE that natively supports EditorConfig, code styling should be handled auto-magically in the background. If not, check if there's an EditorConfig plug-in/package for your editor/IDE that you can install.

EditorConfig Validation via Travis CI

Each PR and commit is tested on GitHub for code styles consistency via Travis CI, using the EClint validator for EditorConfig.

Travis CI validation is performed by the validate.sh script found in the repository root; you can run the script locally to check the integrity status of your repository folder (the script will check all files, including unstaged and ignored ones).

Validating Commits via EClint

You're strongly advised to install EClint and our pre-commit Git hook to validate your changes for code consistency at commit time:

Once installed the pre-commit hook, every time you carry out a commit operation the staged files will be first checked via EClint to ensure that they meet the code styles settings in .editorconfig, and if they don't the commit will fail with an error listing the files that didn't pass the validation test.

NOTE — You can always bypass the pre-commit hook via the --no-verify option, e.g.:

git commit --no-verify

The advantage of using this hook instead of the validate.sh script is that the hook will test only the staged files involved in the actual commit, whereas the script will test every file in the repository folder, including ignored and unstaged files, which is more time consuming and not focused on the specific commit changes.

The git-hook-install.sh script will create the following files inside the repository:

  • .git/hooks/pre-commit-validate.sh — the commit validation script.
  • .git/hooks/pre-commit — the pre-commit hook that launches the validation script.

You can uninstall the Git hook at any time, by executing:

The hook installer and uninstaller scripts are designed to coexist with other pre-commit hooks you might have added to the repository, without disrupting them.