Velocitas create concept

Motivation

To create a project skeleton and automate template generation on GitHub, the command velocitas create is going to be introduced.

We are using RFC2119 to define keywords for requirements.

MUST This word, or the terms "REQUIRED" or "SHALL", means that the definition is an absolute requirement of the specification
MUST NOT This phrase, or the phrase "SHALL NOT", means that the definition is an absolute prohibition of the specification.
SHOULD This word, or the adjective "RECOMMENDED", means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" means that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
MAY This word, or the adjective "OPTIONAL", means that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation that does not include a particular option MUST be prepared to interoperate with another implementation that does include the option, though perhaps with reduced functionality. In the same vein an implementation that does include a particular option MUST be prepared to interoperate with another implementation that does not include the option (except, of course, for the feature the option provides.)

Requirements

#	Description	Remarks
1	`velocitas create` command must be introduced
2	Running `velocitas create` without parameters must guide through the project creation process (aka Interactive Mode), allowing the developer to add APIs and services at creation time which will reference the correct Velocitas CLI packages (either provided by Velocitas or by a 3rd party).
3	In addition to an Interactive Mode, there must be a CLI mode where all of the arguments shall be passable as arguments.
4	To simplify UX-experience default create behavior may be introduced.
5	Environmental per-conditions:
5.1	`velocitas create` command must properly work on the DevContainer based on Ubuntu 22.04 and on default GitHub Runner based on Ubuntu 22.04
5.2	`velocitas create` command should be available locally on Mac, Linux and Windows
5.3	`velocitas create` command may be available locally on Mac, Linux and Windows (with corporate proxy)
5.4	`GITHUB_API_TOKEN` must be provided by a user as an environmental variable
6	Other repository changes
6.1	Files* to be copied by the create command must originate from the respective languages' SDK repositories
6.2	Content of particular `example` folder inside vehicle-app-sdk-lang, where lang is python or cpp, must be independent and runnable as-is
6.3	IDE-related content (e.g. VSCode artifacts) must be prepared in the respective languages' SDK repositories

\ * Files - shall be defined in an implementation phase. Suggestions given in Example Section.

Creation modes

Parameter Mode

velocitas create [FLAGS...]

Create a project based on a set of parameters.

USAGE
  $ velocitas create [FLAGS...]

FLAGS
  -n, --name=<string>          (mandatory) This value will define the Vehicle App name. The folder will be created with the same name. Name will be re-used in the manifest.
  -l, --language=<option>      (mandatory) Defines Project Language. Currently supported values: cpp, python.
  -t, --template               (optional) Default value `false`. Enable content required to generate a template.
  -p, --package=<option>       (optional) Defines which packages must be installed. If not provided - all packages should be installed. 
                               Multiple occurrences are possible. Based on this packages .velocitas.json will be generated.
  --example=<string>           (optional) Specify an example, based on which user Vehicle Application will be generated.
   

EXAMPLES
$ cd /home/user/
$ velocitas create \
    --name=VApp \
    --language=python \
    --package=runtimes[@version] \
    --package=devcontainer[@version] \
    --...

# Project Created.

$ ls
# VApp //folder with default content must be created.

Config Mode

USAGE
  $ velocitas create [FLAGS...]

FLAGS
  --config=create-config.json

create-config.json

{
  // (mandatory) This value will define the Vehicle App name. 
  // The folder will be created with the same name. 
  // Name will be re-used in the manifest.
  "name": "VApp",
  // (mandatory) Defines Project Language. Currently supported values: 
  // cpp, python.
  "language": "python/sdk",
  // (optional) Default value `false`. Enable content required to generate a template.
  "template": "false",
  // (optional) Specify an example, based on which user Vehicle Application will be generated. 
  "example": "SeatAdjuster",
  // (optional) Defines which packages must be installed. 
  // If not provided - all packages should be installed. 
  // Multiple occurrences are possible. Based on this 
  // packages .velocitas.json will be generated.
  "packages":
    [
       "devenv-devcontainer-setup@latest",
       "devenv-github-templates@latest",
       "devenv-github-workflows@latest",
       "devenv-runtimes@latest"
    ]
}

!!! Only one mode can be selected either Config or Parameter one.

Interactive Mode (Default Mode)

If velocitas create is invoked without any parameters, the Interactive Mode must be used.

$ velocitas create

## If GITHUB_API_TOKEN is not found in environmental variables... Raise error!

... Creating a new Velocitas project!
> 1. What is the name of your project?
MyVehicleApp

> 2. Which programming language would you like to use for your project?
[x] Python
[ ] C++

## Fetch possible packages. Enabled all by default.
> 3. Which package would you like to use? (multiple selections are possible)
[x] devenv-devcontainer-setup@latest
[x] devenv-github-templates@latest
[x] devenv-github-workflows@latest
[x] devenv-runtimes@latest

> 4. Which example would you like to use? (only a single selection is possible)
[x] SeatAdjuster
[ ] DogMode
[ ] WiperApp

... Project created!

Actual interactive prompts may vary depending on particular context and content.

Other consideration

In this section collected different implementation ideas to be considered by implementers.

Command Output (example for python)

The output of performing velocitas create command shall be created folder with the name taken from --name and the next content:

SDK Example folder structure proposal

examples/
    | <app1>
        | .vscode
            | .launch.json   // can be generated by extracting from root .launch.json
            | .tasks.json    // tan be generated or TaskProvider* can be used
            ˪ .settings.json // must be omitted
        ˪ app
            | src
            | tests
            | AppManifest.json
            | Dockerfile
            | requirements.in  // required for Vehicle App itself
            ˪ requirements.txt
    | <app2>
    | ...
    | <appN>
    | requirements.in   // requirement for Dev Environment
    ˪ requirements.txt  // requirement for Dev Environment

* Task Provider: https://code.visualstudio.com/api/extension-guides/task-provider