Merge pull request #6441 from Budibase/pro-docs

Pro contributing and CI/CD docs

.github/workflows/README.md

@@ -6,7 +6,7 @@ Welcome to the budibase CI pipelines directory. This document details what each
 ## All CI Pipelines
 
 ### Note
-- When running workflow dispatch jobs, ensure you always run them off the `master` branch. It defaults to `develop`, so double check before running any jobs.
+- When running workflow dispatch jobs, ensure you always run them off the `master` branch. It defaults to `develop`, so double check before running any jobs. The exception to this case is the `deploy-release` job which requires the develop branch. 
 
 ### Standard CI Build Job (budibase_ci.yml)
 Triggers:
@@ -116,3 +116,74 @@ This job is responsible for deploying to our production, cloud kubernetes enviro
 - Kick off cloud deploy job
 - Ensure you are running off master
 - Enter the version number of the last known good version of budibase. For example `1.0.0`
+
+## Pro
+
+### Installing Pro
+
+The pro package is always installed from source in our CI jobs. 
+
+This is done to prevent pro needing to be published prior to CI runs in budiabse. This is required for two reasons:
+- To reduce developer need to manually bump versions, i.e: 
+  - release pro, bump pro dep in budibase, now ci can run successfully
+- The cyclic dependency on backend-core, i.e:
+  - pro depends on backend-core
+  - server depends on pro
+  - backend-core lives in the monorepo, so it can't be released independently to be used in pro
+  - therefore the only option is to pull pro from source and release it as a part of the monorepo release, as if it were a mono package
+
+The install is performed using the same steps as local development, via the `yarn bootstrap` command, see the [Contributing Guide#Pro](../CONTRIBUTING.md#pro)
+
+The branch to install pro from can vary depending on ref of the commit that triggered the budibase CI job. This is done to enable branches which have changes in both the monorepo and the pro repo to have their CI pass successfully. 
+
+This is done using the [pro/install.sh](../../scripts/pro/install.sh) script. The script will:
+- Clone pro to it's default branch (`develop`)
+- Check if the clone worked, on forked versions of budibase this will fail due to no access
+  - This is fine as the `yarn` command will install the version from NPM
+  - Community PRs should never touch pro so this will always work
+- Checkout the `BRANCH` argument, if this fails fallback to `BASE_BRANCH`
+  - This enables the more complex case of a feature branch being merged to another feature branch, e.g. 
+    - I am working on a branch `epic/stonks` which exists on budibase and pro. 
+    - I want to merge a change to this branch in budibase from `feature/stonks-ui`, which only exists in budibase
+    - The base branch ensures that `epic/stonks` in pro will still be checked out for the CI run, rather than falling back to `develop`
+- Run `yarn setup` to build and install dependencies
+  - `yarn` 
+  - `yarn bootstrap`
+  - `yarn build`
+    - The will build .ts files, and also update the `main` and `types` of `package.json` to point to `dist` rather than src
+    - The build command will only ever work in CI, it is prevented in local dev
+
+#### `BRANCH` and `BASE_BRANCH` arguments
+These arguments are supplied by the various budibase build and release pipelines
+- `budibase_ci` 
+  - `BRANCH: ${{ github.event.pull_request.head.ref }}` -> The branch being merged
+  - `BASE_BRANCH: ${{ github.event.pull_request.base.ref}}` -> The base branch
+- `release-develop`
+  - `BRANCH: develop` -> always use the `develop` branch in pro
+- `release`
+  - `BRANCH: master` -> always use the `master` branch in pro 
+
+
+### Releasing Pro
+After budibase dependencies have been released we will release the new version of pro to match the release version of budibase dependencies. This is to ensure that we are always keeping the version of `backend-core` in sync in the pro package and in budibase packages. Without this we could run into scenarios where different versions are being used when installed via `yarn` inside the docker images, creating very difficult to debug cases.
+
+Pro is released using the [pro/release.sh](../../scripts/pro/release.sh) script. The script will:
+- Inspect the `VERSION` from the `lerna.json` file in budibase
+- Determine whether to use the `latest` or `develop` tag based on the command argument
+- Go to pro directory
+  - install npm creds
+  - update the version of `backend-core` to be `VERSION`, the version just released by lerna
+  - publish to npm. Uses a `lerna publish` command, pro itself is a mono repo. 
+    - force the version to be the same as `VERSION` to keep pro and budibase in sync
+  - reverts the changes to `main` and `types` in `package.json` that were made by the build step, to point back to source
+  - commit & push: `Prep next development iteration`
+- Go to budibase
+  - Update to the new version of pro in `server` and `worker` so the latest pro version is used in the docker builds
+  - commit & push: `Update pro version to $VERSION`
+
+
+#### `COMMAND` argument
+This argument is supplied by the existing `release` and `release:develop` budibase commands, which invoke the pro release
+- `release` will supply no command and default to use `latest`
+- `release:develop` will supply `develop` 
+

docs/CONTRIBUTING.md

@@ -190,6 +190,21 @@ yarn mode:account
 ```
 ### CI
  An overview of the CI pipelines can be found [here](./workflows/README.md)
+
+### Pro
+
+@budibase/pro is the closed source package that supports licensed features in budibase. By default the package will be pulled from NPM and will not normally need to be touched in local development. If you require to update code inside the pro package it can be cloned to the same root level as budibase, e.g. 
+
+```
+.
+|_ budibase
+|_ budibase-pro
+```
+
+Note that only budibase maintainers will be able to access the pro repo. 
+
+The `yarn bootstrap` command can be used to replace the NPM supplied dependency with the local source aware version. This is achieved using the `yarn link` command. To see specifically how dependencies are linked see [scripts/link-dependencies.sh](../scripts/link-dependencies.sh). The same link script is used to link dependencies to account-portal in local dev. 
+
 ### Troubleshooting
 
 Sometimes, things go wrong. This can be due to incompatible updates on the budibase platform. To clear down your development environment and start again follow **Step 6. Cleanup**, then proceed from **Step 3. Install and Build** in the setup guide above to create a fresh Budibase installation.