# Contributing to ajsf

ajsf is an open project and welcomes contributions. These guidelines are provided to help you understand how the project works and to make contributing smooth and fun for everybody involved.

There are two main forms of contribution: reporting issues and performing code changes.

## Reporting Issues

If you find a problem with ajsf, report it using [GitHub issues](https://github.com/hamzahamidi/ajsf/issues/new).

A security vulnerability is the exception: report it privately as [SECURITY.md](./SECURITY.md) describes, not in a public issue.

Before reporting a new issue, please take a moment to check whether it has already been reported
[here](https://github.com/hamzahamidi/ajsf/issues). If this is the case, please:

- Read all the comments to confirm that it's the same issue you're having.
- Refrain from adding "same thing here" or "+1" comments. Just hit the
  "subscribe" button to get notifications for this issue.
- Add a comment only if you can provide helpful information that has not been
  provided in the discussion yet.

When creating a new issue, make sure you include:

1. As much detail as possible about your setup/environment
1. Steps to reproduce the issue/bug
1. What you expected to happen
1. What happened instead

This information will help to determine the cause and prepare a fix as fast as possible.

## Code Changes

Code contributions come in various forms and sizes, from simple bug fixes to implementation
of new features.

To send your code change, use GitHub pull requests. The workflow is as follows:

  1. Fork the project.

  1. Create a branch based on `main`.

  1. Implement your change, including tests and documentation.

  1. Run tests to make sure your change didn't break anything.

  1. Publish the branch and create a pull request.

  1. ajsf developers will review your change and possibly point out issues.
     Adapt the code under their guidance until all issues are resolved.

  1. Finally, the pull request will get merged or rejected.

See also [GitHub's guide on contributing](https://help.github.com/articles/fork-a-repo).

If you want to do multiple unrelated changes, use separate branches and pull
requests.

### Prerequisites

This project pins its Node version in `.nvmrc`. Use it, because the Angular version
in use does not support every Node release:

```bash
$ nvm use
```

If `nvm use` leaves you on the wrong version, source nvm with `--no-use` first
(`. "$NVM_DIR/nvm.sh" --no-use`) and run it again. Otherwise the shell keeps your
default Node and installs or builds silently run on the wrong version.

The repository has a `package-lock.json` and no `yarn.lock`, so use npm. CI installs
with `npm ci`.

### Start the development environment

Let's first generate all the bundles we need to start the demo:

```bash
$ cd ajsf
$ npm install
$ npm start
```

You can stop the demo application.
The tricky part now is to run concurrently both the demo application & the library in watch mode.
So, first choose which library you want to change then run `$ ng build @ajsf/core --watch` for example
to build in watch mode the `@ajsf/core`.
Now let's start the demo application in watch mode too. So, open a new terminal and run `$ ng serve` and there you go.
This method is tricky but it works perfectly in all environments (I tried other methods like npm-run-all
or concurrently packages but angular-cli build doesn't restart after a failed build).
If you have a better method please send a PR.

### Running the tests

The library tests run on Vitest through Angular's unit-test builder, in jsdom, so
they need no browser:

```bash
$ npm run test:core -- --no-watch
```

Substitute `test:bs3`, `test:bs4`, `test:bs5`, `test:material` or `test:primeng` for the
other packages. Leave `--browsers` out, because its absence is what selects jsdom.

`npm run test:scripts` runs the tests for the files in `scripts/`. It is plain jasmine
with no browser, so it takes about a second, and CI runs it too.

### Commits

Each commit in the pull request should do only one thing, which is clearly
described by its commit message. Especially avoid mixing formatting changes and
functional changes into one commit. When writing commit messages, adhere to
[Angular Conventional Commit](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines).

#### Commit Message Format
Each commit message consists of a **header**, a **body** and a **footer**.  The header has a special
format that includes a **type**, a **scope** and a **subject**:

```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```

The **header** is mandatory and the **scope** of the header is optional.

Any line of the commit message cannot be longer than 100 characters! This allows the message to be easier
to read on GitHub as well as in various git tools.

The footer should contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages/) if any.

```markdown
docs(changelog): update changelog to beta.5
```

```markdown
fix(release): need to depend on latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users need the latest of these.
```

#### Type

Must be one of the following:

* **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
* **ci**: Changes to our CI configuration files and scripts (example scopes: Circle, BrowserStack, SauceLabs)
* **docs**: Documentation only changes
* **feat**: A new feature
* **fix**: A bug fix
* **perf**: A code change that improves performance
* **refactor**: A code change that neither fixes a bug nor adds a feature
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
* **test**: Adding missing tests or correcting existing tests

#### Scope

The scope should be the name of the npm package affected (as perceived by the person reading the changelog generated from commit messages).

The following is the list of supported scopes:

* **ajsf/core**
* **ajsf/bs3**
* **ajsf/bs4**
* **ajsf/bs5**
* **ajsf/material**
* **ajsf/primeng**
* **locales**
* **demo**
* ...

When the commit fixes a bug, put a message in the body of the commit message
pointing to the number of the issue (e.g. "Fixes #123").

### Pull requests and branches

All work happens in branches. The main branch is only used as the target for pull
requests.

During code review you often need to update pull requests. Usually you do that
by pushing additional commits.

In some cases where the commit history of a pull request gets too cumbersome to
review or you need bigger changes in the way you approach a problem which needs
changing of commits you already did it's more practical to create a new pull
request. This new pull request often will contain squashed versions of the
previous pull request. Use that to clarify the changes contained in a pull
request and to make review easier.

When you replace a pull request by another one, add a message in the
description of the new pull request on GitHub referencing the pull request it
replaces (e.g. "Supersedes #123").

## Releasing (maintainers)

Releases are automated. There is no npm token: publishing uses npm Trusted
Publishing over OIDC, so it only works from this repository's release workflow.

Release only when the published product changes: widget behaviour, the public
API, dependencies, or the supported Angular range. CI configuration, test
suites, lint setup and contributor documentation do not get a release, however
large the diff. They land without touching the version, and the release
workflow then does nothing.

The package major always matches the Angular major it targets, so `@ajsf/* 16.x`
is for Angular 16. Minor and patch are free.

1. Set the version. One script writes it to all six packages, along with the
   internal `@ajsf/core` range and the Angular peer ranges, because setting those
   separately is how a package ships resolving to the previous core:

   ```bash
   $ npm run version:set -- 16.1.0 16
   ```

   The second argument is the Angular major. The script refuses to write anything
   if it disagrees with the version, or if the version is malformed.

2. Commit the change, open a pull request, and merge it once CI is green.

3. Approve the `npm-publish` deployment. Nothing reaches npm before this.

4. The workflow publishes `@ajsf/core` first, then the five framework packages,
   and tags the commit afterwards.

A version containing a hyphen (`16.0.0-rc.1`) publishes to the `next` dist-tag
instead of `latest`, so it does not change what `npm install @ajsf/core` resolves
to. Do not create release tags by hand: the workflow writes them, so a tag always
means that version shipped.