Background

• Make --split (-s) the default behaviour #74
• Compile time evaluation #57

To help guide people to generate efficient code, we want to make splitting source code into multiple files the default behaviour. This however would be a breaking change that would bring with it potential confusion if made on its own.

Instead, we should consider making the decision to split sources a conscious one during a transitional phase.

Changes

In this change, I update the split flag to remove the default value of false and instead define an inversion that introduces the --no-split flag.

This means that when running create-api without specifying -s, --split or --no-split, you will now get an error:

$ create-api generate schema.json 
Error: Missing one of: '--split', '--no-split'
Help:  --split <split>  Split output into separate source files.
Usage: create-api generate [<options>] <input> --split
  See 'create-api generate --help' for more information.

If you already used -s or --split everything is ok, but if you didn't, you will be forced to make a decision:

1. Continue with --no-split
2. Transition to using --split

To help guide users about this decision, I added some more discussion to the flag when using --help:

$ create-api generate schema.json --help
USAGE: create-api generate [<options>] <input> --split

ARGUMENTS:
  <input>                 The OpenAPI spec input file in either JSON or YAML format

OPTIONS:
  --output <output>       The output folder (default: ./.create-api/)
  --config <config>       The path to generator configuration. If not present, the
                          command will look for .create-api.yaml in the current
                          directory. (default: ./.create-api.yaml)
  -s, --split/--no-split  Split output into separate source files.

        Merging the source files offers a compact output, but prevents the compiler
        from parallelizing build tasks resulting in slower builds for larger
        schemas.

        It's recommended that you use --split, but behaviour prior to 0.1.0 matched
        --no-split.

        In a future version, these flags will be deprecated and replaced with an
        alternative opt-out flag instead. For more information, see
        https://github.com/CreateAPI/CreateAPI/issues/74

  -v, --verbose           Print additional logging information
  ...

As a result in 0.1.0 you are forced to make a decision. In a future version however, we will relax this again by deprecating --split and --no-split and replacing it with a more clearly named --merge-sources flag which defaults to false.

Release Note

• You are now required to explicitly pass the --split or --no-split flag when running the generator. --no-split matches the default behaviour prior to 0.1.0 but it is recommended to split your sources for improved build times of your generated code. For more information, see #74.