Development Process

This page details the development process that should be following when contributing to projects in the OpenActive ecosystem

Code Quality

New code should, as much as possible, lead to increased coverage of:

• ESLinting

• TypeScript type checking (where applicable)

so that the codebase becomes more reliable over time.

More generally, the rule is: "Leave it at least as good as you found it. Preferably, a little better ☺️".

TypeScript type checking of JavaScript projects

All new OpenActive web or Node.js projects should be written in TypeScript using .ts files.

However it would be an arduous task to migrate existing OpenActive JavaScript projects to TypeScript. Instead we leverage JSDoc annotations to use TypeScript to check for type errors. For more information about this, see Type Checking JavaScript Files.

Type checking is performed by running:

npx tsc

This is included in the test NPM script of these projects so that this check is performed by CI.

Commits

Conventional commits are used throughout the projects. This standard makes reading commit messages easier for both humans and automated tools.

An example of a conventional commit message is:

feat: Add test case for prepayment always required

Pre-commit hooks

In some projects when code is committed, pre-commit hooks are run. This could include processes such as documentation generation, test execution, and TypeScript types generation. These pre-commit hooks are executed using husky.

If commits using the VSCode GUI are failing, try attempting the commit from the console to see any pre-commit hook errors.

Pull Request Process

All changes to all projects are made through Pull Requests on GitHub.

Each Pull Request:

• must resolve or partially resolve an existing issue in GitHub and this issue must be referenced in the Pull Request description

• must have one or more reviewers

• must have a conventional commit message (see above)

• if applicable, should have proof of testing for the fix included in the PR description. Screenshots that demonstrate the application's new and correct behaviour are a good approach to do this

• must be small where possible; long-running branches are best avoided

An example of a PR with a conventional commit message, reviewer, and GitHub issue reference

The process for contributing is as follows:

1. Create a branch off master/main called feature/{branch_name} (the exception to this is when contributing to both Reference Implementation and Test Suite at the same time, see below for information)

2. Add changes that resolve existing issue, ensuring documentation is also updated to reflect any changes

3. Run tests locally (usually npm test)

4. Create a draft PR in Github after pushing changes, and ensure CI passes

5. Move PR out of draft and add one or more reviewers

6. Review - this likely involves responding to comments, and ultimately, getting the PR approved by reviewer(s)

7. Merge into master/main by contributor, and ensure CI passes in master/main

8. (Check the GitHub Action fun on master/main to see if the merge triggers the auto-creation of PRs within the repos of other tools. For the dependency graph see https://openactive.io/infrastructure-monitor/. If so, the contributor must review the downstream auto-generated PRs and merge.)

Creating branches when working on Reference Implementation and Test Suite

When contributing to Reference Implementation and making a change that affects Test Suite test coverage, the branches in both projects must be called coverage/{branch_name}. For more information on this see "Reference Implementation And Test Suite Overview"

Referencing Local Packages in Node

Some projects have other OpenActive projects as dependencies, and for certain changes it will be necessary to change these dependencies. For ease of development and reviewing, these dependency changes should be tested locally with the original contribution change.

This can be done in Node by referencing the filepath of the local dependency in the project package.json, as shown below.

Two examples of referencing local packages in the package.json

Debugging in VSCode

VSCode provides powerful debugging tools that aid the development experience.

For existing projects, debugging configurations are likely to have been set up. They can be found by clicking on the "Run and Debug" icon on the Activity Bar, and then selecting the appropriate Launch Configuration from the dropdown list at the top of the "Run and Debug" view.

Some features of debugging in VSCode that are particularly helpful are:

• Breakpoints

• Conditional Breakpoints

• Data inspection

• Logpoints

More information about debugging in VSCode can be found here.