https://semver.org/

Stay on versions 0.x until everything is really stable. Release v1.0 when SURFACE is in wide-spread use and no longer having breaking changes.

4. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

If SURFACE is always deployed with docker then dependencies changes like no longer supporting Python3.8 or upgrading the Django version are no longer breaking change

Changes to public interfaces including data contracts and API contracts

• REST API changes (adding new end points doesn't break)
• Model changes if they change the public API
• Possibly removing template blocks that user customized templates could rely on
• Possibly removing CSS classes that user customized templates or JavaScript could be using
• Removing or changing reusable Python processes / modules that other software could be using
• Change Django major version number (dropping compatibility)

Consider using commitizen to help with versioning (but requires following it's process for commit messages).

Explicitly set major_version_zero = true (although this is the default it makes it clear that you're not yet moving to v1.0).

[tool.commitizen]
major_version_zero = true

cz commit

# Prompts you with questions like:
# ? Select the type of change: (feat/fix/docs/style/refactor/test/chore)
# ? What is the scope of this change? (optional)
# ? Write a short description:
# ? Provide a longer description: (optional)
# ? Is this a BREAKING CHANGE? (y/N)

cz bump

# → Bumps to v1.3.0 (e.g. minor bump due to 'feat')
# → Updates version in files
# → **Generates changelog entry**
# → Commits: "bump: version 1.2.3 → 1.3.0"
# → Tags: v1.3.0

SURFACE doesn't need to be available from PyPI or installable with pip. It may not need pyproject.toml in the short term (unless needed for conf options for tools like black).

It probably doesn't need to make us of Poetry/PDM etc. But, it may benefit from pip-tools to generate a lock file for the exact dependencies being used in a particular docker build version.

pip-compile - Generates lock files from requirements

# Create requirements.txt from requirements.in
pip-compile requirements.in

# Update specific package
pip-compile --upgrade-package django

# Upgrade all packages
pip-compile --upgrade

pip-sync - Syncs environment to match lock file exactly

# Install/uninstall to match requirements.txt exactly
pip-sync requirements.txt

# Sync multiple files
pip-sync requirements.txt dev-requirements.txt

There's no reason for other SURFACE users to have to build the docker image if they want a stable release version.

Using pip-tools (where requirements.txt has been generated with pip-compile) will ensure reproducible for a given docker image version.

# Dockerfile
COPY requirements.txt .
RUN pip install -r requirements.txt  # Exact versions every time

We can also improve security with

# Generate with hashes for supply chain security
pip-compile --generate-hashes requirements.in

# Development
echo "django>=4.0" > requirements.in
echo "pytest" > dev-requirements.in

# Lock versions for production
pip-compile requirements.in
pip-compile dev-requirements.in

# Build consistent Docker image
docker build -t surfacecdms:v1.2.3 .

# Push to container repo
docker push registry.com/surfacecdms:v1.2.3

This combination gives you the best of both worlds: flexible development with requirements.in and robust production deployments with locked requirements.txt in immutable container images.

All SURFACE documentation in the repo so that documentation gets versioned. Make it easy to edit using markdown.

Consider using Docsify, a fully client-side solution (no build step) where:

• Markdown (.md) files live in /docs
• An index.html loads in the browser
• No build step, no server
• The browser reads and renders .md files at runtime

/docs/
  index.html (loads docsify.min.js from a CDN)
  README.md (becomes homepage)
  my_page.md

Add with some basic tests

SURFACE main branch requires approval before merge and requires linear history (rebasing). We're living in the future - consider also requiring mandatory signed commits.

Given that we need Python 3 to be installed for most things that we do, it seems reasonable to use pip as the package manager for installing SURFACE. One option would be to create a new project on PyPI called surface-installer (which will give users the surface command line tool).

Installing SURFACE involves coordinating infrastructure provisioning, software orchestration (including docker container deployment) and configuring. One option is to collaborate on a shared package, that surface-installer can use as a dependency, to provision infrastructure (e.g Clound instances or local VMs using Proxmox VM using terraform), orchestrate software to available hosts (using ansible) and configure the environments.

I've started work on copa for this purpose. The idea is that SURFACE, wis2box and other projects can have there own individual installers that use copa as a dependency. When multiple projects that have copa based installers are being installed then some services can be easily shared.