Skip to content

Checklist for publishing new integration

Ilya Taratukhin edited this page Oct 23, 2023 · 27 revisions

This is a living document and is subject to change.

For preparing the repository to release, please check the next steps.

Repository name

  • The repository name should follow naming conventions.
  • main branch instead of master branch is used.

Versioning

  • We use semver for our repos
  • In develop state start with 0 major version (0.0.1, 0.1.0...)
  • Make major release 1.0.0 only when the product passed the integration checklist and was tested by another teammate
  • In most of our repos we use semantic-release to automate the versioning process. You can find its example configuration in our template repository

Tags

Use the list of tags below to describe Fingerprint integration:

<programming-language>, browser, detection, fingerprint, 
identification, fingerprinting, browser-fingerprinting, browser-fingerprint, 
fraud-detection, fraud, audio-fingerprinting, fingerprintjs, fingerprintjs-pro,
visitor-identifier

Dedicate a maintainer

It's essential to decide who's going to be responsible for the repository. Every repository needs to have an owner (a person or a team) who will actively:

  • set the right expectations about the project
  • keep the repository in a good shape

Mark this user into the CODEOWNERS file. See an example.

Community profile

Fill out the next parts

  • Description
  • Readme
  • Contributing
  • License

Badges

Use badges to make it easy to find basic information about the status of the project.

Examples:

  • Build status Build status
  • Current NPM version Current NPM version
  • Discord server Discord server
  • Documentation Discord server

Documentation

  • Write usage documentation in the website integrations section
  • Write API documentation in the repository, add a link to usage documentation at the website
  • Prepare the integration page for the dashboard App Settings section.
  • The readme communicates the supported versions of internal dependencies (e.g. supported versions of React, Node.js, or react-native) and sets correct expectations for future updates and supported versions. We have an awesome guide how to write the Readme.

Tests

Include at least a basic set of (unit) tests. You can add code coverage to improve the repository's appearance. Use this pr as a guide.

Continuous Integration

Set up a build agent - GitHub Actions

  • Make it run tests
  • Fail builds on failed tests

Security

  • Protect the main branch
  • Access to the repository should be granted only to groups, not users
  • Use integrations group for writing access
  • Use a special group for admin access
  • Setup dependabot for detecting vulnerabilities

Secrets

  • Don't add sensitive secrets without environment
  • You can put to the repository non-sensitive secrets for testing like requestId and publicKey
  • Use production environment for sensitive deploy secrets like registry tokens and GH_RELEASE_TOKEN. Protect this environment and add reviewers for approving workflow before run.

Review

Ask teammates for review to check the following things:

  • Code is supportable and does what it should
  • There are no secrets and other sensitive data in the repository
  • Try to use this integration as a client

Publishing

  • Don't automate the publishing of sensitive packages.
  • Use environments to store secrets, not in Repository secrets or Organization secrets
    • Restrict branches that allowed to run publishing workflow
    • Require review before starting publishing workflow

Misc

  • A repository contains CHANGELOG.md.
  • A repository utilizes tags and releases feature.
  • Integration send integrationInfo with each request
  • Before releasing 1.0.0 version Readme should contain WIP warning
    > :warning: **Work in progress**: This is a beta version of the library
    
  • For Server SDKs make sure that they will not crash in case of a broken data contract from the Server API, for the test you can use get_event_extra_fields.json as mock.