@ou-imdt/utils/contributing.md

Utility library for interactive media development

# Contribution guidelines

Thank you for considering contributing to our utils library! This document provides the guidelines required for contributing effectively.

## Getting started

1. Clone the repository:

```sh
git clone git@bitbucket.org:lts-imd/utils.git
```

2. Install dependencies:

```sh 
npm install
```
## Working with branches

### Update your local `dev` branch:

Ensure your local `dev` branch is up-to-date with the remote `dev` branch.

```sh
git checkout dev
git pull
```

### Create a new branch off `dev`:

Use the format of feature/[utilname]-dev

### Development practices:

- Use `feature/` for new developments (to dev).
- Use `bugfix/` for bug fixes (to dev).

- Always prefer `git pull --rebase` to avoid unnecessary merge commits.
```sh
git pull --rebase origin dev
```
- If any conflicts during the rebase resolve them. If you want to abort the rebase for a reason:
```sh
git rebase --abort
```

### Commit messages

Use following format for commit messages:

- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: white-space, formatting that doesn't affect code meaning
- refactor: A code change that neither fixes a bug nor adds a feature
- test: Adding/updating tests
- chore: Changes to the build process, tools, scripts 

### Making changes

1. Develop on your private dev branch.

> For a new utility, create a test file. If you are unsure how to write tests, contact one of the contributors.

2. Push changes:
   
Once you have completed your changes, push them to your branch.

```bash
git push origin <branch-name>
```
3. Create a pull request:

> run tests and make sure all tests are passed.

 Initiate a pull request from your branch to the `dev` branch for review.

### Review and merging

#### Code Review:

All changes will be reviewed by assigned reviewers before merging.

#### After Merging:

Once your changes have been merged, mark the JIRA issue (if any) as resolved.


## Commands reference

Execute these commands from the project's root directory:

| Command       | Action                       |
| ------------- | ---------------------------- |
| `npm install` | Installs dependencies        |
| `npm test `   | Runs tests                   |
| `npm build`   | builds the component library |


## Local testing:

Run npm link in the Utils root directory to test the locally installed package.

Run npm unlink utils to remove the local package.

> You can read more about npm-link in the [npm documentation](https://docs.npmjs.com/cli/v10/commands/npm-link).

```bash
npm link @ou-imdt/utils
npm unlink @ou-imdt/utils
```

## Pre-publish tasks:

- Bump the version number in package.json and update changelog.md.

- npm publish dry run: run below script to get a preview of the files that will be published.

```bash
npm publish --dry-run
```

- Git commit and push the changes to `dev`.

- Send a PR to main, the Bitbucket pipeline will run and publish the new version 🚀.

> !! Below steps are for manual publish you don't need them anymore but keeping here if we ever need to do it again.

- Check if logged in to npm: npm whoami. If not logged in, login to npm: npm login

- Publish the package by running:
```bash 
  npm publish --access public
```