Skip to content

Commit

Permalink
Merge pull request #15 from PAIR-code/dev
Browse files Browse the repository at this point in the history 
docs: improve docs
  • Loading branch information
@iislucas
iislucas authored Oct 27, 2024
2 parents a66c0a7 + 9f87d54 commit accaceb
Show file tree
Hide file tree
Showing 2 changed files with 162 additions and 140 deletions.
154 changes: 154 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,157 @@ All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
information on using pull requests.

### Environment

To set a clean environment for development you can first run `npm clean-install`
to download dependencies.

### Testing

To run unit tests:

- `npm run test:ci` - Run tests once, with extra long timeout.
- `npm run test:dev` - Run tests continuously, rerunning on code change.
- `npm run test:trace` - Run tests once, with `--trace-warnings` and `verbose`.

Running `npm test` will invoke `test:dev`.

### License: Apache 2.0

Source code for this library is released under the [Apache 2.0
license](https://spdx.org/licenses/Apache-2.0.html). Each source code file MUST
start with an [SPDX](https://spdx.dev/) license header at the top of the file
that matches the one here:
[`.github/license-check/header-Apache-2.0.txt`](.github/license-check/header-Apache-2.0.txt).
To check whether all source files have such a header, you can run:

```sh
npm run lint
```

The full text of the Apache-2.0 license is available in the accompanying
`LICENSE` file.

### Linting

This project uses [ESLint](https://eslint.org/) to enforce code style, including
checking the license headers. To run:

```sh
npm run lint
```

The output will tell you if there are any lint errors or files missing the
license header. If there are no lint errors, the command will produce no output.
To automatically add the right headers, and do other automated lint fixes, you
can run:

```sh
npm run lint --fix
```

If you are using Visual Stuido Code with the official [Microsoft ESLint
extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint),
files will be automatically checked as you edit them.

### Checking Code Style

This project defines and checks code style with
[Prettier](https://prettier.io/). Invoke Prettier from the command line via the
following:

- `npm run prettier:check` - Check _.js and _.ts files for style conformance.
- `npm run prettier:write` - Overwrite files with Prettier applied style.

NOTE: If you're using Visual Studio Code, the [Prettier
extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
will apply code style on save.

### Commit messages

Commits to this codebase should follow the [conventional
commits](https://www.conventionalcommits.org/en/v1.0.0/) format:

```
<type>[<scope>]: <short summary>
│ │ │
│ │ └─⫸ Summary in present tense. Not capitalized. No period at the end.
│ │
│ └─⫸ Commit Scope: optional short phrase of scope
│
└─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test
[optional body]
[optional footer(s)]
```

The `<type>` should be one of the types specified by the [Angular Commit Message
Format](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format):

- `build`: Changes that affect the build system or external dependencies.
- `ci`: Changes to our CI configuration files and scripts (semantic-release, GitHub Actions).
- `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.
- `test`: Adding missing tests or correcting existing tests.

The `<description>` should be a sentence describing the change (capitalized
first word, trailing punctuation).

For example, if you fixed a bug in the way `reaction events are handled`, your
commit message might look like this:

```sh
git commit -m "fix: correct reaction event handling"
```

Our release process uses these commit messages to determine the next version
number and to automatically generate the release `CHANGELOG.md` file. So it's
important that your commit messages are clear and meaningful.

## Releasing, Github Actions, and publishing to NPM

New releases are made by merging the `dev` branch into `main`, once you do this,
the workflow for releasing is triggered in github:
`.github/workflows/release_workflow.yaml`. The two key secret variables used for
the release are `GH_TOKEN=...` which has a github personal access token with
permissions as specified in the `release_workflow.yaml`; and `NPM_TOKEN=...`
which has the npmjs.com token that allows writing to the [`ts-llmt`
npm](https://www.npmjs.com/package/ts-llmt)

The release workflow uses
[semantic-release](https://github.com/semantic-release/semantic-release) to
actually do the release; the config file for relasing is:
[`.release.json`](.release.json). Note that the semantic release configuration
uses
[@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer)
to look at commit messages (which are assumed to be formatted according to
[convensional commits](https://www.conventionalcommits.org/en/v1.0.0/)) and
figure out how to change semantic version numbers. This is basically, +1.0.0
(and reset to M.0.0) for Major non-backward compatible changes; +0.1.0 and reset
to M.F.0 for Feature addition changes that are backward compatible, and +0.0.1
for Bugfixes. The semantic-release flow also closes bugs, makes a github
release, and adds labels to pull requests on github. Lots of stuff you might
otherwise try and do by hand.

You can manually run `npx semantic-release` from the `main` github branch.
You'll first need to locally set `GH_TOKEN=...` and `NPM_TOKEN=...`
appropriately.

But the basic thing this does is just run some npm releasing commands, namely:

```sh
npm publish
```

So in a pinch, you can just update versions manually, and run that to deploy.

Note there are two github workflows defined in this project in:

- `.github/workflows/dev_workflow.yaml`: triggered for every pull request
- `.github/workflows/release_workflow.yaml`: tiggered on every merge into the
main branch (which is intended to indicate that we should be making a relase).
148 changes: 8 additions & 140 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,147 +38,15 @@ whatIsAtoB.substs({ thing: 'table', thing2: 'chair' });
expect(whatIsTabletoB.escaped).toEqual('what is a table to a chair?');
```

## Environment

To set up your environment for development, first run `npm clean-install` to
download dependencies.

## Testing

To run unit tests:

- `npm run test:ci` - Run tests once, with extra long timeout.
- `npm run test:dev` - Run tests continuously, rerunning on code change.
- `npm run test:trace` - Run tests once, with `--trace-warnings` and `verbose`.

Running `npm test` will invoke `test:dev`.

## Linting & License headers

This project uses [ESLint](https://eslint.org/) to enforce code style, including
checking the license headers. To run:

```sh
npm run lint
```

If there are no lint errors, the command will produce no output.

NOTE: If you're using Visual Stuido Code with the official [Microsoft ESLint
extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint),
files will be automatically checked as you edit them.

### License: Apache 2.0
## License: Apache 2.0

Source code for this library is released under the [Apache 2.0
license](https://spdx.org/licenses/Apache-2.0.html). Each source code file MUST
start with the [SPDX](https://spdx.dev/) license header in the file
[`.github/license-check/header-Apache-2.0.txt`](.github/license-check/header-Apache-2.0.txt).

To check whether all source files have such a header, run `npm run lint`. The
output will tell you if there are any files missing the header. `npm run lint
--fix` will add headers for you.

The full text of the Apache-2.0 license is available in the accompanying
`LICENSE` file.

## Checking Code Style

This project defines and checks code style with
[Prettier](https://prettier.io/). Invoke Prettier from the command line via the
following:

- `npm run prettier:check` - Check _.js and _.ts files for style conformance.
- `npm run prettier:write` - Overwrite files with Prettier applied style.

NOTE: If you're using Visual Studio Code, the [Prettier
extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
will apply code style on save.

## Commit messages

Commits to this codebase should follow the [conventional
commits](https://www.conventionalcommits.org/en/v1.0.0/) format:

```
<type>[<scope>]: <short summary>
│ │ │
│ │ └─⫸ Summary in present tense. Not capitalized. No period at the end.
│ │
│ └─⫸ Commit Scope: optional short phrase of scope
│
└─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test
[optional body]
[optional footer(s)]
```

The `<type>` should be one of the types specified by the [Angular Commit Message
Format](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format):

- `build`: Changes that affect the build system or external dependencies.
- `ci`: Changes to our CI configuration files and scripts (semantic-release, GitHub Actions).
- `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.
- `test`: Adding missing tests or correcting existing tests.

The `<description>` should be a sentence describing the change (capitalized
first word, trailing punctuation).

For example, if you fixed a bug in the way `reaction events are handled`, your
commit message might look like this:

```sh
git commit -m "fix: correct reaction event handling"
```

Our release process uses these commit messages to determine the next version
number and to automatically generate the release `CHANGELOG.md` file. So it's
important that your commit messages are clear and meaningful.

## Releasing, Github Actions, and publishing to NPM

New releases are made by merging the `dev` branch into `main`, once you do this,
the workflow for releasing is triggered in github:
`.github/workflows/release_workflow.yaml`. The two key secret variables used for
the release are `GH_TOKEN=...` which has a github personal access token with
permissions as specified in the `release_workflow.yaml`; and `NPM_TOKEN=...`
which has the npmjs.com token that allows writing to the [`ts-llmt`
npm](https://www.npmjs.com/package/ts-llmt)

The release workflow uses
[semantic-release](https://github.com/semantic-release/semantic-release) to
actually do the release; the config file for relasing is:
[`.release.json`](.release.json). Note that the semantic release configuration
uses
[@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer)
to look at commit messages (which are assumed to be formatted according to
[convensional commits](https://www.conventionalcommits.org/en/v1.0.0/)) and
figure out how to change semantic version numbers. This is basically, +1.0.0
(and reset to M.0.0) for Major non-backward compatible changes; +0.1.0 and reset
to M.F.0 for Feature addition changes that are backward compatible, and +0.0.1
for Bugfixes. The semantic-release flow also closes bugs, makes a github
release, and adds labels to pull requests on github. Lots of stuff you might
otherwise try and do by hand.

You can manually run `npx semantic-release` from the `main` github branch.
You'll first need to locally set `GH_TOKEN=...` and `NPM_TOKEN=...`
appropriately.

But the basic thing this does is just run some npm releasing commands, namely:

```sh
npm publish
```

So in a pinch, you can just update versions manually, and run that to deploy.
license](https://spdx.org/licenses/Apache-2.0.html). The full text of the
Apache-2.0 license is available in the accompanying [`LICENSE.md`](./LICENSE.md)
file.

Note there are two github workflows defined in this project in:
## Contributing

- `.github/workflows/dev_workflow.yaml`: triggered for every pull request
- `.github/workflows/release_workflow.yaml`: tiggered on every merge into the
main branch (which is intended to indicate that we should be making a relase).
See the [`CONTRIBUTING.md`](./CONTRIBUTING.md) file for details of how to
contribute, setup your environment, run tests, check license headers, style, and
format your commit messages.

0 comments on commit accaceb

Please sign in to comment.