[NOT READY] Versioning Strategy for digital-land-frontend

[DilwoarH]

Versioning Strategy for digital-land-frontend

Summary

Introduce a proper versioning and release strategy for the digital-land-frontend package to prevent downstream breakages caused by consuming the main branch directly.

Background

Nearly all consumers of the digital-land-frontend package are currently using the main branch rather than referencing a specific version or tag. As a result, any changes merged into main are immediately reflected in all consuming repositories - often without adequate testing or preparation — leading to unexpected breakages and unstable builds.

Motivation

• Prevent regressions or breaking changes from affecting consumers.
• Improve the confidence and predictability of using digital-land-frontend.
• Align with industry best practices around dependency management.
• Enable safer, faster development without fear of downstream impact.

Proposal

We propose to adopt semantic versioning and publish the digital-land-frontend package with version tags for both npm and pip.

For npm Consumers

• Use semantic versioning (MAJOR.MINOR.PATCH) for all releases.

• Publish all new versions to the public or internal NPM registry.

• Add npm version commands in the CI/CD pipeline to create release tags.

• Consumers should update their package.json to reference a specific version (e.g., ^1.2.0) instead of pointing to main:

  "dependencies": {
    "digital-land-frontend": "^1.2.0"
  }

• Consider publishing pre-release versions (e.g., 1.3.0-beta.1) for early feedback.

For pip Consumers

• Package should be distributed via an internal or public PyPI repository.

• Add proper setup.py or pyproject.toml metadata to define version.

• Use GitHub releases or tags to mark official versions.

• Consumers should install via a versioned release, not via Git URLs:

  pip install digital-land-frontend==1.2.0

• Consider automating releases using tools like twine, poetry, or GitHub Actions.

Implementation Plan

1. Audit current usage in downstream projects.
2. Set up automated release workflows for NPM and PyPI publishing.
3. Define initial stable version (e.g., 1.0.0) and tag it.
4. Update all downstream repositories to use the new version.
5. Document release process and update contribution guidelines.

Alternatives Considered

• Continue using main: This is not sustainable due to high fragility and downstream impact.
• Lock to commit hashes: Reduces fragility but lacks semantic meaning and version management.

Risks

• Some consumers may not update immediately and might break if main is changed again before switching.
• Introducing versioning requires discipline around changelog management and semantic version bumps.

Conclusion

Introducing versioning will make digital-land-frontend a more stable and maintainable package. This discussion proposes a structured release process that aligns with best practices and safeguards consumers against unintentional changes.