Development
This describes the development process of the company project (mycompany-orchescala/helper.scala).
Make sure helper.scala is executable:
cd ~/dev-mycompany/mycompany-orchescala
chmod +x helper.scala
Note
To update this project, use cd .. and then ./helperCompany init - see [Init Company].
update
./helper.scala update
Updates the company project itself (build files, wrappers, 00-docs scaffolding).
The API page every project ships (03-api/OpenApi.html and 03-api/PostmanOpenApi.html, written
by the project's ./helper.scala update and uploaded by its publish) comes with orchescala:
the documentation app in 04-orch-doc is built into the orchescala-orch-doc jar, a dependency
of the helper - nothing to build or configure in the company. The page loads the yml named like
itself.
publish
Creates a new Release for the Company project (company-orchescala) and publishes to the repository(e.g. Artifactory)
Usage:
./helper.scala publish <VERSION>
Example:
./helper.scala publish 0.2.5
The same steps are executed as for the publish command in any project.
See project publish.
Company Documentation
This is a semi-automatic process. This should be done either to prepare a Release or after a Release.
Note
At the moment this is based on using Postman and a WebDAV server.
So get in touch if you have a different setup.
Do the following steps:
- Open the
company-orchescalaproject in your IDE. - Configure the Release - edit
00-docs/CONFIG.conf. - Copy the actual Production Versions of the Release (
00-docs/VERSIONS.conf) to00-docs/VERSIONS_PREVIOUS.conffrom [Postman]. - Copy the new Versions of the Release to
00-docs/VERSIONS.conffrom [Postman].
// START VERSIONS
// Workers
companyAccountingWorkerVersion = "1.8.11"
...
// Project
companyAccountingVersion = "0.8.11"
...
// END VERSIONS
See [Deploy the Projects]
prepareDocs
Prepare the company documentation.
./helper.scala prepareDocs
Warning
Be aware that this overwrites release.md
prepareDocs ends with a local preview of the documentation site: the site is assembled into
00-docs/site (this company and its siblings, the project APIs at their released versions,
orch-spec with its catalog, orch-ops) and served - the URL is printed (Preview ready: http://localhost:3004/)
and the command keeps running until you stop it with Ctrl-C. A failure in the spec catalog or
the sibling repos does not stop the preview, it is printed and the preview continues with what is
available. Everything needed ships with orchescala; Node.js is only used for the orch-spec
catalog (skipped without it).
The preview port is 3004 by default. A company changes it in its CompanyOrchescalaDevHelper, e.g.
when two companies preview on the same machine:
override protected def docsPreviewPort: Int = 3003
Each company has a folder for orch-spec and one for orch-ops: 00-docs/testdata/spec and
00-docs/testdata/ops. prepareDocs creates them, and the preview shows the path on the start
screen of both apps (with a copy button - in the folder dialog on macOS paste it with ⌘⇧G). A browser
cannot be given a folder, so it is linked once per preview port; the browser remembers it afterwards.
Other folders:
override protected def docsSpecDir: os.Path = os.home / "specs" / "my-company"
override protected def docsOpsDir: os.Path = os.home / "ops" / "my-company"
- Manually adjust the Release Notes release.md - and check the result in the local preview
(run
prepareDocsagain, ornpm run sitein orch-doc).
publishDocs
Release the company documentation.
./helper.scala publishDocs
Builds the documentation site (this company and its siblings, the project APIs at their released
versions, orch-spec, orch-ops) into 00-docs/site and uploads it to /site on the WebDAV server. /site
is never deleted as a whole: the projects' own folders (/site/<company>/<project>/, published
by each project) and the classic sites of older releases (/site/<company>/<tag>/) stay - only
assets/, spec/ and ops/ are replaced. Needs Java and git only - Node.js just for the orch-spec catalog.
The site links two apps in its top bar: Spec (spec/, process specifications) and Ops
(ops/, the recurring errors in operation with their workarounds - a counter per error, search,
status tags, screenshots). Orch Ops keeps its data in a shared folder of its own (local or
SharePoint), chosen in the app - the site only serves the app.
Note
The documentation apps (Orch Doc, Orch Spec, Orch Ops) are licensed under the Business Source License 1.1: non-production use is free, production use - publishing the site for a company - needs a license from z9nai GmbH.
- Check the result on your Company Documentation Page (
<documentationUrl>/site/#/<company>).