1.0.0

[jonaslagoni]

1.0.0

One point that has been up to discussion for a while now, is when should we release 1.0.0, I have always added more and more issues to the milestone, and then started removing them again. From my perspective what 1.0.0 shows are:

• The main objective with 1.0.0 is a stable API that does not suddenly break.
• (Maybe a controversial point) It signals a maintained and organized library.
• (Maybe a controversial point) A library that has great docs so it is easy for people to get started learning about its use-cases and features.
• (Maybe a controversial point) It should be easy for people to contribute to it, to various degrees.

The last 3 points kinda sum up #457.

When is the right time

To start the discussion, from my perspective, there is never a right time, I am always saying "let's just fix this, and then it can be stable", but it is a never-ending thought. Especially since I know that in the future there lie some breaking changes (especially in terms of supporting union types), so I am really biased, as I lean more towards not moving to 1.0.0. Also in terms of documentation, there are multiple open issues, that make the documentation incomplete.

But I definitely also see the benefits of just jumping out into 1.0.0 as it shows a different image to whoever finds the library.

So when do you think we should do it? And what prerequisite do you see we got to address before it can happen?

[zsim0n]

Here are a few unsolicited thoughts :

• 1.0.0 implies a message to the outer world that you are confident with the product. It can be used in other projects in production. People can trust you did your best to make it work.

• Choosing the versioning scheme is kind of personal and could express the speed of the change (does a version 26 mean there were 25 major breakings or direction changes?)

last but not least

• be prepared to maintain major versions and communicate the lifecycle (beta-GA-sunset-unsupported)

[derberg]

be prepared to maintain major versions and communicate the lifecycle (beta-GA-sunset-unsupported)

I don't think this is needed. It is like with versioning frequency, up to you how you solve it. It is not mandatory to support major versions. Just nice to have and IMHO it is completely fine to say only latest major is supported and nobody backports bug fixes

[jonaslagoni]

Another thing that is tough to tackle, is what changes to the generated output are considered breaking changes after moving to v1.0.0?

For example, we have a bunch of edge cases, where we need to adapt the output, to fit into the language constraints. In a sense fixing such a case will result in different generated models, that will not work with your existing code that utilizes them.

Given the input:

{
    {
      $id: 'TestModel',
      type: 'object',
      additionalProperties: false,
      properties: {
        testProp: {
          $id: 'TestEnum',
          type: 'string',
          enum: ['test+'],
        }
      }
    }
}

it would generate the following output:

export class TestModel {
  private _testProp: TestEnum;

  constructor(input: {
    testProp: string
  }) {
    this._testProp = input.testProp;
  }

  get testProp(): string { return this._testProp; }
  set testProp(testProp: TestEnum) { this._testProp = testProp; }

}
export enum TestEnum {
  TEST = "test+"
}

Then you have your own code, using these models:

import { TestModel } from './TestModel';
import { TestEnum } from './TestEnum';

const model = new TestModel();
model.testProp = TestEnum.TEST;

With #497 we now generate the enum key differently and actually handle the special case, so we get the key TEST_PLUS instead of TEST, rendering your code unusable until you change the code to model.testProp = TestEnum.TEST_PLUS;.

So how do we handle such a use-case once we move to a stable version? Should we consider this a breaking change or just a fix, as we are now.