Paneron host application

Development

Testing

Loading local extensions

Use Paneron settings window to specify directories with built extension packages. Paneron will attempt to load versions in those directories whenever corresponding extensions are requested.

This is useful if an extension is not published in the registry because it’s private, or if published extension version is outdated (e.g., during testing).

Troubleshooting steps

Considering %APP_DATA% directory is under, e.g., $HOME/Library/Application Support/Paneron under macOS:

Delete %APP_DATA%/plugins: This drops any plugins
Delete %APP_DATA%/index-dbs: This drops LevelDB-backed dataset indexes
Delete %APP_DATA%/state: This drops LevelDB-backed app UI state

Developing in a container

Pre-requisites: Docker (tested with Docker Desktop).

Containerized LSP

The provided tsserver.Dockerfile has all the dependencies and launches TypeScript language server in stdio mode as default command. Use your IDE’s host to communicate. Tested with Neovim 0.7.

Containerized `yarn run dev`

Note	This is not a well-tested flow. Works under macOS Monterey with glitches.

Ensure your host machine has an X11 server running and accepting connections from network clients (on macOS, there is an option XQartz preferences and you may additionally need to execute xhost +localhost).

Use the provided Dockerfile to build and run the image:

docker build -t paneron-dev .
docker run \
  -e DISPLAY=host.docker.internal:0 \
  --build-arg "project_path=/paneron" \
  -v "$(pwd)/runtime-config:/paneron/.config" \
  --privileged \
  paneron-dev

The -v flag makes it so that the $HOME/.config directory, containing among other things Paneron & Electron runtime data on Ubuntu, is mounted within your project’s working directory for easier debugging.

Developing without a container

Note	Development environment has been tested on macOS Monterey and Ubuntu 18.

You’ll need the following installed:

macOS: Xcode and the accompanying command-line tools
Node 16 (installation: Ubuntu, macOS)
Yarn (installation)
Ubuntu: libsecret-1-dev (may or may not be installed by default) and some frontend such as gnome-keyring. (See also Dockerfile for how those are installed in a headless setup.)

From project root, run yarn and then yarn run dev.

Working on bundled libraries

If you are working on RegistryKit or ExtensionKit, you may need to run the app with their local versions rather than those installed from NPM.

The convention for now is to 1) place or symlink their compiled versions in a special directory under project root:

mkdir -p dependencies-local
# either
cp -R /path/to/your/registry-kit/dist dependencies-local/registry-kit-dist
# or
ln -sf /path/to/your/registry-kit/dist dependencies-local/registry-kit-dist

then 2) replace their package.json entries with relative paths (but don’t commit this change):

-   "@riboseinc/paneron-registry-kit": "^1.2.3",
+   "@riboseinc/paneron-registry-kit": "file:./dependencies-local/registry-kit-dist",

…then, after you’re done making changes to RegistryKit and corresponding changes to Paneron core, 3) release the new version of the library (e.g., RegistryKit) and update the package.json record to use that version (instead of the local path) before you commit your changes to Paneron:

-   "@riboseinc/paneron-registry-kit": "file:./dependencies-local/registry-kit-dist",
+   "@riboseinc/paneron-registry-kit": "^1.2.4",

Making changes

Here are conventions regarding working with Git, commit messages and release flow.

Committing

This repository is set up with AngularJS commit message convention. Pre-commit hook will invoke interactive prompt, powered by Commitizen, that will ask you for information and put together a commit message for you.

To make sure you follow the convention:

Only use git commit when making commits
Don’t use built-in IDE commit prompts, since they may bypass prepare-commit-msg hook

Pulling

It is recommended to use “rebase” behavior of pull (make sure to use a fresh version of Git) by having this in your global .gitconfig:
```
[pull]
    rebase = true
```
When pulling, Commitizen commit prompt may appear even if there is no merge commit to be made. You can dismiss it with Ctrl+C.

Pushing

There is a pre-push Git hook that compiles the app. This helps us catch compilation errors before code reaches CI.

Automated testing

Currently, the test suite works on macOS only (with yarn test-mac-e2e), and requires the app to be compiled and built first (which makes it very slow to run).

Releasing

CI builds the application automatically, and attaches build artifacts to release tag that matches the version in package.json if that release is still a draft.

Release sequence

When starting the work on a new version:

Create a release draft on GitHub (tag name should be in the form of “v1.2.3” and release title can be anything).
Update version in package.json (package version should be in the form of “1.2.3”).
Push your commits as usual.

After your final push, when you think this version is ready:

Wait until CI run completes, and artifacts for each platform are attached to release draft.

You may check build logs for each platform, looking for “publishing” in Build/release step, to make sure all artifacts were indeed uploaded at the end.

If, for example, version in package.json during push did not match the draft release you want to publish, then CI will silently skip attaching updated build artifacts to the draft, and binaries attached to the draft will be outdated.
Perform QA/tests against artifacts attached to the draft. (Make sure that the artifacts attached are of correct versions, there are no regressions, and features work as intended.)
If QA/tests succeeded, change release status from draft to published.
Repeat from the top.

ribose-jeffreylau/paneron