yaclt/CONTRIBUTING.md

Yet Another Change Log Tool

# Contributing

[[toc]]

## Dependencies

Before you get started with contributing, you'll need to install some tools.

### Node.js

I recommend installing the LTS release of Node.js. It can be installed from the [Node.js website](https://nodejs.org/) or via [Node Version Manager (nvm)](https://github.com/nvm-sh/nvm).

### Yarn

The easiest way to install `yarn` is to install Node.js first, then use `npm`: `npm i -g yarn`

## Setting Up Your Environment

Currently, the development tools are only tested on macOS and Linux. They may work on Windows, but have not been tested (see [#139](https://github.com/mrjones2014/yaclt/issues/139)).

- Clone the project with `git`.
- In the project directory, run `yarn` to install dependencies. **Ensure you see something like "husky hooks installed" in the output.** Code changes that have not been run through `prettier` and `eslint`, or command changes which do not update `COMMANDS.md` **will not pass the CI pipeline**. The Husky hooks should handle this all for you, as long as they have been installed.
- **Do not use the `npm` package manager, it will generate a `package-lock.json`. We use the `yarn` package manager and a `yarn.lock` file.**

## Your First Contribution

If you're new to Typescript and/or contributing to open source, check out the list of [good first issues](https://github.com/mrjones2014/yaclt/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).

If you have a little more experience, feel free to take a look at some of the other issues.

In general, `eslint` and `prettier` will enforce most of the code style and convention rules. You should run `yarn lint` before pushing commits to GitHub to ensure they will pass the automated checks. In addition to this, you should also try to file the conventions
in place for file structure (e.g. utility functions should go in a file under `src/utils/`, CLI-related code should go under `src/cli/`, actions-related code should go under `src/actions/`, etc.). All code should be written
in Typescript (**no Javascript**).

## Branch Naming

It is **strongly recommended** to name your branch with the following syntax: your name, initials, or GitHub username in all lowercase, followed by a slash, then the issue number you're working on, then a brief `kebab-case`
description of the issue or the issue title. Example: `mrjones2014/1234-title-of-issue-1234`.

If you name your branch this way, the changelog generator will be able to automatically parse the issue number from your branch name and add it to the generated changelog entry for you. For more information
on generating changelogs, see [Generating a Changelog Entry](#generating-a-changelog-entry).

You may choose whatever branch name you like, but if you don't match the recommended format, you will need to enter the issue number into the changelog entry manually.

## Submitting Pull Requests

When submitting a Pull Request, **make sure you fill out the Pull Request template.** Pull Requests without this filled out will not be reviewed until it is filled out. If you exclude any part of it,
you should provide a valid explanation as to why that part is not applicable. Please also make sure test your own code with the provided testing instructions before requesting a review.

Please do not submit Pull Requests which do not resolve an open issue. If you would like to make a Pull Request for which no open issue corresponds, please open the issue. Every Pull Request **must resolve an open issue.**

### Generating a Changelog Entry

Every Pull Request **must** contain a changelog entry, generated by this tool. Please read through [README.md](./README.md) and [COMMANDS.md](./COMMANDS.md) to get familiar with the command line interface.
To generate a changelog entry, you may either use a reasonably up-to-date global installation of `yaclt`, or you may use the project-local version. To use the project-local version of the CLI, first run
`yarn build` to ensure the build is up-to-date, then `./dist/index.js` will be the CLI entrypoint and accept all the same arguments as `yaclt`. For example:

```sh
./dist/index.js new --changeType IMPROVED -m "Your changelog message goes here"
```

The change types we use in this project are the default list: `IMRPOVED`, `NEW`, and `FIXED`.

**Pull Requests must include a changelog entry generated by this tool.**

## Submitting Issues

When submitting issues, please be sure to use one of the provided templates, and be sure to fully fill out the template. You should be as detailed as possible, and use a clear and descriptive title.
For bug reports, it can help to include what version of `yaclt` you are using, and the name and version of the operating system you are using.

**Please be sure to search for similar issues before opening a new one.**