Versioning strategy

[aminosbh]

Since this is a fork of the archived jgraph/mxgraph and since it changed its name to maxGraph, it is a good chose to rest the version number, what I noticed in the package.json files.

It is always a good practice to use a clear versioning strategy to reduce the cognitive load for everyone developing and using this library. These days the Semantic Versioning approach is followed by many (maybe majority) of libraries and softwares.

... we propose a simple set of rules and requirements that dictate how version numbers are assigned and incremented. ... For this system to work, you first need to declare a public API. ... Once you identify your public API, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version.

Regrading the current status of the project which is maybe prune to heavy changes in the public API, I suggest that we my start with version 0.1.0 as @tbouffard proposed in his draft #87 . The Semantic Versioning 4th rule states that the major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

When publishing a pre-release we just have to add a prefix like -alpha -beta -beta.1 -beta.2 -rc
The Semantic Versioning spec do not add any further rules concerning 0.y.z version but we can just apply the same rules for the x.y.z where x >= 1in a best effort way.

Proposal:

• Start with version 0.1.0-alpha for internal usage and testing. (Could be event published on npm this way)
• Increment the PATCH when integrating bug fixes
• Increment the MINOR when adding new feature and/or refactoring and/or removing features.
• When you think that others can use it and you want their feedback from a user point of view (developer that integrates this library), publish the version without -alpha suffix or replace it with a -beta suffix (i.e. 0.2.5-beta). IMO I do not think it's necessary to use a -beta suffix for 0.y.z versions since they are all considered in the development phase.
• When things get stabilized enough, publishing the 1.0.0 series could start (start with -alpha -beta -rc suffix)

Notes:

• We can create a dedicated issue related to the roadmap of the 0.1.0 version.
• The old ChangeLog file must be taken into consideration. It may be archived or we can simply add a separator to start a new chapter.

Related issues/discussions:

• chore: improve the configuration to build the npm package #87
• Steps required for publishing package #41
• ES9 conversion and validation #18 (reply in thread)

[tbouffard]

In #87, I initially updated the version in the package.json files from 1.0.0 to 0.1.0 as a transition phase: at that time, we haven't decided yet what the versioning will be, but fore sure, we are not ready for v1 😄
In the past, we previously mentioned versioning but without taking any decisions. So thanks @aminosbh for rising this issue!

I am in favor of a new versioning scheme, as proposed in the issue description

• not continuing the existing mxGraph one
• sticking to SemVer
• starting with v0.1.0 and to do not move to v1 until the API is stabilized

From a user perspective, restarting the versioning scheme makes sense: this is a new library, so there is no reason to continue with the existing mxGraph versioning scheme. I am not convinced that using v5 would help existing mxGraph users (as a reminder, the latest mxGraph version is 4.2.2).

From a technical view, the repository contains all original mxGraph tags, for instance v4.2.0, v4.2.2 and the former Changelog file. The changelog part is quite easy to manage (see issue description). For the tags, we could rename them or drop them all as they are available in the original mxGraph repository. Eventually, we could keep track of the relation between the commit hash and the tags

[UPDATE 2022-06-09]: about the tag, we may not have any issue if we decide to tag the repo with the name of the package as we have a monorepo. Like this is done in https://github.com/rollup/plugins/tags

[aminosbh]

Oh thank you @tbouffard I forgot about the tags. I like the idea of renaming the deprecated tags. What do you think about using a prefix like legacy-v4.2.2 ? Since using a prefix like mxgraph-v4.2.2 will be too confusing because of the one-character difference ! I think also that we may rename the current main branch to legacy and why not make the development the new main branch. Making this "radical" changes may be possible in this stage (before publishing packages) without any impact.

[Edit] Do you mean that we may name the new tags as maxgraph-v0.1.0, maxgraph-core-v0.1.0 or maxgraph-html-v0.1.0 ?

[tbouffard]

Hi, sorry for the late answer
For the tag, I meant what you mentioned or maxgraph-core@0.1.0. But it was only if we keep the original tags.
We are going to release a single package for now, and if we have several packages to release in the future, we will probably release all of them at the same time. So having a single tag per release seems more convenient for now. So v0.1.0 seems ok.

For the tag rename, legacy-v4.2.2 is ok to me. Generally, I don't like tags rename/change as it may break forks or environment, but here I don't see a solution to manage the new versioning scheme and the existing tags. We could put the information in the README, in the paragraph where we talk about the mxGraph history for instance. See #93 for instance.
I am also ok with the branch rename, we can do it later as well.

[tbouffard]

Hi
I've been thinking about renaming the mxGraph tags and I am not sure anymore that we need to keep them. This is legacy code and these tags can be found in the original mxGraph repository: https://github.com/jgraph/mxgraph/. I don't know if anybody will be interesting in looking at the mxGraph original history.
In any case, we cannot keep them with their existing name, and renaming or deleting them introduces the same kind of change in the repository and will break the existing clones.
Thus, the arguments for choosing renaming or deletion cannot be guided by technical reasons.

My new proposal is

• to remove them
• eventually, document in the changelog the git sha related to each removed tags

What do you think about this new proposal @mcyph @junsikshim @aminosbh @cd-yang @csouchet?
This is one of the last issues that prevents us from releasing a first version of the npm package (a long overdue request).

[junsikshim]

I agree that keeping the existing tags doesn't bring any value to this project. Starting from v0.1.0 sounds good to me.
Also, renaming the current main to legacy and creating a new main from development makes sense.
I'm not sure when is the best time to do them, but I fully agree :)

[JeremyJonas]

Any updates on this? Seem this is the only issue blocking alpha release and publishing this to npm.

maxGraph is under active development. An alpha version will be released soon (along with the npm package) once the #92 issue has been resolved.

FWIW:

• I agree that legacy tags have no value moving forward, as they are archived and retrievable from the mxGraph predecessor repo.
• Please use proper Semver for this!
• Starting with v0.1.0 makes sense and based on Semver is aligned with intent of non-stable library. No need -alpha/-beta for pre v1, best to reserve those for mature pre-release candidates. If you are still undecided about versioning specifics, you could publish it now as 0.1.0-alpha at this stage while you wait to finalize this discussion, as this is considered a mature pre-release targeting 0.0.1 - that would enable consumption while this is pending.

Really looking forward to using this library, thank you for keeping it alive and migrating to TypeScript, huge improvement and investment - thank you!

[csouchet]

Hi I've been thinking about renaming the mxGraph tags and I am not sure anymore that we need to keep them. This is legacy code and these tags can be found in the original mxGraph repository: https://github.com/jgraph/mxgraph/. I don't know if anybody will be interesting in looking at the mxGraph original history. In any case, we cannot keep them with their existing name, and renaming or deleting them introduces the same kind of change in the repository and will break the existing clones. Thus, the arguments for choosing renaming or deletion cannot be guided by technical reasons.

My new proposal is

* to remove them

* eventually, document in the changelog the git sha related to each removed tags

What do you think about this new proposal @mcyph @junsikshim @aminosbh @cd-yang @csouchet? This is one of the last issues that prevents us from releasing a first version of the npm package (a long overdue request).

Hi @tbouffard,
I'm sorry for the late answer.

I'm ok with your proposal 🙂

[tbouffard]

Hi, thanks for the recent feedback. I was waiting to get several opinions before doing something.
Let's start implementing the "version 0.1.0" proposal to move forward.

[tbouffard]

Hi, I should be able to work on the topic in a few days.
In the meantime, I have create a 0.1.0 milestone to hold all issues related to the upcoming version:

[tbouffard]

I have just performed the latest actions we agreed on:

• Former mxGraph tags have been removed with the following command: git tag -l | xargs -n 1 git push --delete origin
• Create docs: list former mxGraph tags in CHANGELOG.md #140 to list the commits related to former tags
• Created tag v0.0.1 c60dfa8
• Don't forget to run the following command to update tags locally: git fetch --all --tags --prune