Skip to content

packaging.md

Latest commit

 

History

History
191 lines (130 loc) · 7.07 KB

packaging.md

File metadata and controls

191 lines (130 loc) · 7.07 KB
navTitle Packaging Guidelines

Packaging Guidelines

This section describes the requirements we have for all GitHub repositories, and npm modules we maintain.

To help ensure all of the requirements are met, an issue should be raised in FlowFuse/admin{rel="nofollow"} using the New Repository Checklist and then worked through.

GitHub projects

Naming

  • FlowFuse Components should start with flowfuse-
  • If a Node-RED plugin/node should start with nr-
  • Installers or Orchestration projects are named without the leading flowfuse- e.g. installer or helm

Settings

  • A rule should be added under the projects settings/branches to prevent pushing directly to the main branch
  • The Do not allow bypassing the above settings rule should be ticked when creating the branch rules

Content

All Git Repositories must contain the following files:

  • README.md
  • LICENSE

Linting

All code repositories should adopt our standard linting rules by copying the .eslintrc from the FlowFuse/.github repository.

If a repository has any additional requirements for linting, such as handling Vue code, then additional plugins can be added.

We use StandardJS, with one exception - 4 spaces not 2.

Notifications

Repositories should be added to the appropriate Slack channel. For core code repositories, this would be in the #gh-flowfuse channel.

To create a subscription, go to that channel and type the message:

/github subscribe FlowFuse/NAME-OF-REPO comments reviews

This will subscribe to any notifications covering: issues, pulls, commits, releases, deployments, comments and reviews.

Workflows

Project Automation

All code repositories must have the Project Automation workflow added. This is done by adding .github/workflows/project-automation.yml. This workflow will ensure any opened issues are automatically added to the Product board where it can be triaged and prioritised.

Release Publish

For any repositories that contain modules to be published to npm, they should also have a copy of .github/workflows/release-publish.yml.

This workflow will publish to npm whenever the repository is tagged with a vX.Y.Z format tag.

Note that each repository may have slightly different pre-publish requirements - for example if there is a build step or not. You may need to customise the workflow to match what is needed.

Private Repositories

For private repositories, you will also need to add a Repository Secret as they cannot access the organization-wide secret we have in place.

  1. Generate a Personal Access Token with repo, write:org scope.

  2. Add it as a Repository Secret to the Private Repo (https://github.com/FlowFuse//settings/secrets/actions) with the name PROJECT_ACCESS_TOKEN

Labels

We have a standard set of labels that should be applied to all repositories. This ensures we have a consistent approach to planning and tracking of work.

The definitive list of labels is maintained here and are synchronized across all repositories via GitHub Actions.

  • Type: epic, story, task, bug, artwork
  • Sizing: XS - 1, S - 2, M - 3, L - 5, XL - 8, XXL - 13
  • Area: area:docs, area:db, area:migration, area:frontend, area:api, area:device, area:billing, area:infrastrucutre, area:install, design
  • Priority: priority:high, priority:medium, priority:low
  • Status: blocked, consideration
  • Product Scope: scope:devices, scope:enterprise, scope:node-red, scope:collaboration
  • Other: good first issue, upstream, needs-triage, headline, backport, research

New repositories must be added to the list in flowforge-repositories.yml, and then the Synchronize Labels action manually run.

NPM packages

Naming

Note: we are migrating to the @flowfuse scope of packages. See this issue for details. This section of the handbook will be updated as part of the migration.

  • All packages should be scoped to @flowforge

Node-RED plugins should start with nr- e.g.

  • @flowforge/nr-storage
  • @flowforge/nr-auth

FlowFuse plugins should start with forge- e.g.

  • @flowforge/forge-driver-localfs
  • @flowforge/forge-driver-docker
  • @flowforge/forge-driver-k8s

Content

The package.json must contain the following keys

  • description
  • repository 
    "repository": {
   "type": "git",
   "url": "git+https://github.com/FlowFuse/flowforge.git"
},
  • homepage 
    "homepage": "https://github.com/FlowFuse/flowforge#readme",
  • bugs 
    "bugs": {
    "url": "https://github.com/FlowFuse/flowfuse/issues"
},
  • license
    • Apache-2.0
    • SEE LICENSE IN ./LICENSE
  • author 
    "author": {
    "name": "FlowFuse Inc."
},
  • engines 
    "engines": {
  "node": ">=16.x"
}

Package Version Numbering

Package numbers should follow the Semantic Versioning Scheme as laid out on semver.org.

Each component will stay in step with the core flowforge/flowforge release numbering for major.minor but will increment their own fix values as needed. e.g. On release of v0.2.0 all components will tag and release v0.2.0, but can independently release v0.2.1 as needed.

Major and minor releases will follow the schedule laid out in the Cadence section of the handbook.

A Fix release can be made at any time, depending on the best judgement of the engineer making the fix but requires a review by another team member.

The process for making a release is documented here.

Adding NPM packages to Stacks

As we build more FlowFuse specific nodes we will need to add these to the Stacks

Localfs

Currently bundled packages for the localfs driver need to be added to the nr-launcher package.json and the path to the node needs to be added to the nodesDir array in the lib/launcher.js file (around line 70). This will be updated in the next release to be controlled by the driver-localfs project

Docker

Any nodes or themes should be added to the package.json in node-red-container/ directory of the docker-compose project

K8s

Any nodes or themes should be added to the package.json in node-red-container/ directory of the helm project