Pull requests and releases

A good pull request is small, tested and explains itself. This page lists what to do before you send one and what to expect. It ends with how a release is made, because a contribution reaches users only through a release. Send pull requests to github.com/kwebby/cutscript. Read the README.md, LICENSE and NOTICE in its root before you do.

Before you write anything

• Read the code of conduct. It applies to every issue, pull request and discussion.
• Report security problems privately. Follow the security page. Do not describe a vulnerability in a public issue or pull request.
• Talk first about a large change. A new feature, a change to the edit model or a new dependency is easier to agree on before the code exists than after. Start in Contributors in the community forum, then open an issue on GitHub, then the pull request. Questions, ideas and early bug reports go to the forum. Confirmed bugs and pull requests go to GitHub.
• Know the licence. Cutscript is under the GNU AGPL-3.0-only, with an additional permission for linking with Remotion (see NOTICE). Your contribution is made under the same terms. Send only code and assets that you wrote or that carry a licence that allows it. See Licences.

Make the change

1. Create a branch for one change. Keep unrelated fixes out of it.
2. Follow the conventions in How the code is organised: Prettier, explicit return types, tests beside the code.
3. Add or update a test for what you changed. Pure logic in src/shared is the easiest to test, and many modules there already have a test file beside them.
4. If you changed a button, a label or behaviour, name the docs page that describes it in your pull request. The docs are part of the website, not this repository, so the page is updated separately. A docs change never needs an app release.
5. Do not edit generated or pointer files by hand: CHANGELOG.md (it only points to the website's changelog), resources/design-exemplars/index.json and resources/native.

Run the checks

Run these before you push.

If you changed packaging, build an unsigned app with node scripts/build-local-app.mjs --unsigned --out <folder>. It runs the packaging checks. See Build from source.

Dependencies

The project keeps its dependency list short, and the AI director's packages are pinned to exact versions. A test, scripts/approved-packages.test.mjs, lists every direct dependency and fails when one is added without the list changing. A new direct dependency needs the project owner's approval first, and the reason belongs in your pull request. The licence gate refuses GPL, LGPL, AGPL and unknown licences for any third-party npm package that ships.

The ffmpeg inside the app is a build without x264 and x265. Do not swap in a build that has them. The packaging checks fail if one reaches a build.

Write the pull request

Say what changed and why, in plain words. Add:

• a screenshot or a short recording for anything a user can see;
• how you tested it, and on which macOS version if it touches recording or permissions;
• the docs pages that need updating, if any;
• a note when the change is visible to users. Maintainers write the release notes in scripts/changelog-notes.mjs when a release is cut, and publish them on cutscript.dev/changelog. Never edit CHANGELOG.md by hand.

Version numbers change only in a release, so leave them alone.

A maintainer will read the change, run the checks and may ask for changes. Small, focused pull requests are reviewed faster than large ones.

How a release is made

Releases are cut by maintainers. A contributor does not need to do any of this, but it explains what happens to a merged change.

1. Release notes. The new beta is added at the top of RELEASES in scripts/changelog-notes.mjs, each item a finished sentence. The newest entry's version must equal APP_RELEASE.semver. The notes are published on the website; the repository's CHANGELOG.md only points there.
2. Version numbers. One release changes these together, and src/shared/release.test.ts checks them: APP_RELEASE in src/shared/release.ts, version in package.json, and mac.bundleShortVersion and mac.bundleVersion in electron-builder.yml.
3. Build and notarize. node scripts/build-local-app.mjs builds the app. When a Developer ID Application certificate is in the keychain, it signs the app. When a notarytool keychain profile is available (its name comes from CUTSCRIPT_NOTARY_PROFILE), it notarizes and staples the app. It then runs the packaging checks. Notarization needs full Xcode.
4. The DMG. node scripts/build-dmg.mjs wraps the newest signed, notarized build in a disk image, then signs, notarizes, staples and Gatekeeper-checks the image itself. Only a signed, notarized app goes into an installer.
5. Publish. The signed and notarized DMG goes to a GitHub release, and the Download button on the website sends visitors to the latest release's DMG. The release notes are published on cutscript.dev/changelog, and each release's notes link there.

A release is the only way new code reaches the people using Cutscript. The bundle identifier, com.cutscript.app, and the signing identity are frozen. Changing either makes macOS drop the permissions people have granted.

Related

• Build from source
• How the code is organised
• Add a skill or a Design pack graphic