nestdotland / roadmap

Roadmap for Nest
2 stars 0 forks source link

Publishing a module [outdated] #6

Closed SteelAlloy closed 4 years ago

SteelAlloy commented 4 years ago

Publishing a module

Publishing a module on nest.land can be done in three different ways. Each of these options may be found in the nest module #2.

Side note: since this module is not just a CLI, a name for this module must be discussed. (I don't thing cli or nest-cli would be a good name.)

CLI

The command line interface can be used independently or with configuration files.

nest publish [name] [...options]

# Global options
-h, --help                                - Show this help.
-d, --debug                               - Print additional information.
-q, --quiet                               - Suppress diagnostic output.
-o, --output-log                          - Create a log file after command completion.
-G, --gui                                 - Perform the task in the gui.

# Miscellaneous
--dry-run                                 - No changes will actually be made, reports the details of what would have been  
                                          published.
--hands-free                              - Don't display the confirmation message with the staged files.

# Common config
--entry               <value:string>      - The main file of your project.
--full-name           <value:string>      - The name of your project, if long. Not a description.
--description         <value:string>      - A description of your module that will appear on the gallery.
--homepage            <value:url>         - A link to your homepage. Can also be a repository.
--version             <value:version>     - Set the version.
--release-type        <value:release>     - Increment the version by the release type.
--unstable                                - Flag this version as unstable.
--unlisted                                - Hide this module/version on the gallery.

# Files
--files               <values...:string>  - All the files that should be uploaded to nest.land. Supports file globbing.    
--ignore              <values...:string>  - All the files that should be ignored when uploading to nest.land. Supports
                                          file globbing.

# Checks
--check-format        [value:string]      - Automatically format your code before publishing
--check-tests         [value:string]      - Test your code.
--check-installation                      - Simulates a dummy installation and check for missing files in the dependency
                                          tree.
--no-check                                - Don't perform any check.

By default all boolean options are set to false.

Checks are a special case. By default all checks are performed.

To disable this behavior, use --no-check. Individual checks take precedence over option --no-check. This means that with nest publish --no-check --check-installation, only the installation check will be carried out.

Default values

the default values are not defined as such in the CLI options. Indeed, they must be determined further by merging all the parameters.

Config Files

Configuration files can be used so you don't have to rewrite the same configuration every time you publish.

egg

The egg file exists in two formats, json and yaml.

To discuss:

  • Should the file be located at the root of the project or in the .nest folder?

The command line options have priority over the fields in the egg file. The file will be rewritten if the parameters have changed at runtime. For example if a new version is determined or if command line options have been provided that differ from the fields in the configuration file.

interface Config {
  $schema: string; // Validates the structure of JSON data

  name: string;
  fullName: string;
  entry: string;
  description: string;
  homepage: string;

  version: string;
  releaseType: semver.ReleaseType;

  unstable: boolean;
  unlisted: boolean;

  files: string[];
  ignore: string[];

  checkFormat: boolean | string;
  checkTests: boolean | string;
  checkInstallation: boolean;
  noCheck: boolean;
}

The options are the same as on the command line.

The egg file is automatically added to the list of ignored files.

.eggignore

The .eggignore file is an extension of the egg file. It takes precedence over ignore.

To discuss:

  • Should the file be located at the root of the project or in the .nest folder?
  • .eggignore, .nestignore or nestignore ?

Files and directories to be ignored are specified one by line, as a glob expression. They follows the same rules as the .gitignore pattern format.

In addition to this syntax, the keyword @extends allows to import other ignore files.

When extending the .gitignore file, .git*/** is automatically added to the list of ignored file.

The .eggignore file is automatically added to the list of ignored files.

Programmatically

Publishing a module is possible by calling the publish function provided by nest.

This is the same function used by the CLI after parsing the options. This means that egg and .eggignore files are taken into account.

import { publish } from "https://x.nest.land/[NEST]@[VERSION]/commands/publish.ts"

publish(name, options);

/********************************/

async function publish(name: string, {
  help: boolean,
  debug: boolean,
  quiet: boolean,
  outputLog: boolean,

  dryRun: boolean,
  handsFree: boolean,

  fullName: string,
  entry: string,
  description: string,
  homepage: string,

  version: string,
  releaseType: semver.ReleaseType,

  unstable: boolean,
  unlisted: boolean,

  files: string[],
  ignore: string[],

  checkFormat: boolean | string,
  checkTests: boolean | string,
  checkInstallation: boolean,
  noCheck: boolean,
})

GUI

The graphical interface will allow authors to ensure that all the parameters of their module are correct and modify fields on the fly. Uses the publish function under the hood.


Once all files have been read and prioritized, some fields are required. If they are not present, the publication will fail.

The only data that will not be undefined for sure when publishing are: