projen 0.76.5 → 0.76.7

package/docs/python.md

@@ -1,169 +0,0 @@
-# Python Projects
-
-Before creating a new project, make sure you have the version of Python you want
-to use set up in your terminal. Running `which python` on UNIX/macOS or
-`Get-Command python` on Windows should print the path to the python version you
-want to use.
-
-To create a new Python project, use `projen new python`:
-
-```shell
-$ projen new python --name=my-project
-```
-
-This will synthesize a standard project directory structure with some sample
-code.
-
-```shell
-├── my_project
-│   ├── __init__.py
-│   ├── __main__.py
-│   └── example.py
-└── tests
-    ├── __init__.py
-    └── test_example.py
-```
-
-The default options will setup a Python environment using `venv`, and will
-create a `requirements.txt` file for installing dependencies via `pip`.
-
-The `projen new` command will also generate a `.projenrc.py` file which includes
-the definition of your project with any options you specified in the command
-line:
-
-```python
-from projen.python import PythonProject
-
-project = PythonProject(
-    author_email="Author email",
-    author_name="Author name",
-    module_name="your_python_project",
-    name="project_name",
-    version="0.1.0",
-)
-
-project.synth()
-```
-
-To modify your project definitions, edit `.projenrc.py` and run `projen` again
-to re-synthesize your project. The following sections describe the various features of Python projects.
-
-## Managing environments, dependencies, and packaging
-
-Every Python project must have a component for managing/installing dependencies,
-a component for managing the Python virtual environment, and if it is a library,
-a component for packaging the library. Some components satisfy multiple
-requirements. See the list below:
-
-- pip: dependency manager
-- venv: environment manager
-- setuptools: packaging manager
-- poetry: dependency, environment, and packaging manager
-- pipenv (TBD): dependency and environment manager
-- conda (TBD): dependency and environment manager
-
-By default, pip, and venv will be used, along with setuptools if the project is a library:
-
-```python
-from projen import ProjectType
-from projen.python import PythonProject
-
-project = PythonProject(
-    ...
-    project_type=ProjectType.LIB
-)
-```
-
-But these can be swapped out as needed by using the provided flags, for example:
-
-```python
-from projen.python import PythonProject
-
-project = PythonProject(
-    ...
-    pip=False,
-    venv=False,
-    setuptools=False,
-    poetry=True
-)
-```
-
-## Dependencies
-
-Python projects have two types of supported dependencies:
-
-1. Runtime dependencies (or just "dependencies").
-2. Development dependencies
-
-You can define dependencies when defining the project itself:
-
-```python
-from projen.python import PythonProject
-
-project = PythonProject(
-    ...
-    deps=[
-        'Django@3.1.5',
-        'aws-cdk.core',  # implies"@*"
-    ],
-    dev_deps=[
-        'hypothesis@^6.0.3',
-    ]
-)
-```
-
-Or using the APIs:
-
-```python
-project.add_dev_dependency('hypothesis@^6.0.3');
-```
-
-Notice the syntax for dependencies:
-
-```text
-<module>[@version]
-```
-
-Where `module` is the module name and `version` is the [semantic version
-requirement](https://semver.org) for the dependency. The semver syntax will be
-converted to the appropriate dependency manager syntax in synthesized files. For
-example, `lib^3.1.0` will be converted to `lib>=3.1.0, <4.0.0` in
-`requirements.txt`.
-
-### Poetry Dependencies
-
-When using the `poetry` project type, note the following:
-
-* The `[@version]` part of the dependency declaration must be present for all dependencies
-* Dependencies that require additional metadata regarding extras etc. may be declared as
-  follows:
-
-  ```text
-  deps: [
-    ...
-    "mypackage@{version = '^3.3.3', extras = ['mypackage-extra']}",
-  ],
-  ```
-
-## Unit Testing with Pytest
-
-The `Pytest` component adds support for writing Python tests with
-[pytest](https://pytest.org/). The component will add the required test
-dependencies to your project.
-
-Test sources are placed under `tests` and can be executed via `projen test`.
-
-To disable pytest tests, set `pytest: false` when you define the
-`PythonProject`.
-
-## `projenrc.py`
-
-## Packaging and Publishing
-
-Python projects can be packaged by using either the `Setuptools` or `Poetry`
-component. `Setuptools` records package metadata within a traditional `setup.py`
-script, while `Poetry` stores metadata in the more-recent `pyproject.toml` file
-format as introduced in PEP 518.
-
-Run `projen package` to generate a source distribution and wheel, and run
-`projen upload` to upload the package to PyPI.

package/docs/releases.md

@@ -1,191 +0,0 @@
-# Releases and Versioning
-
-Projen takes care of managing versioning and releases of your project.
-
-The release model is based on (scaled) [trunk-based development](https://trunkbaseddevelopment.com/) and relies on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) and [Semantic Versioning](https://semver.org/)
-to automatically determine the next version for every release.
-
-This means that commits to the default branch (`main`) are considered ready for production and by default every commit will be released and published to package managers.
-
-## Initial development phase
-
-New projects start with version `0.0.0`.
-Anything may change at any time and public APIs should not be considered stable.
-Commits marked as a breaking change will increase the *minor* version. All other commits will increase the *patch* version.
-
-Projen will **never** release `v1.0.0` without your intervention. Once the project is ready, you have to make a one-time change to bump the major version.
-
-## Major Versions
-
-To bump the major version for the default branch, set the `majorVersion` option to the desired version and push the change.
-For example:
-
-```js
-majorVersion: 1
-```
-
-For major versions 1 and above, if a release includes `fix` commits *only*, it will increase the *patch* version.
-If a release includes any `feat` commits, then the new version will be a *minor* version.
-
-## Prerelease Versions
-
-To release prerelease versions from the main branch, set the `prerelease` option to the desired prerelease prefix.
-For example:
-
-```js
-prerelease: 'beta'
-```
-
-You can also use this with release branches or manual releases (see example below).
-
-## Breaking Changes
-
-Conventional Commits allows changes to be marked as breaking by appending a `!` after the type/scope in the commit message or adding a `BREAKING CHANGE:` footer ([see examples](https://www.conventionalcommits.org/en/v1.0.0/#examples)).
-
-If a release includes breaking changes and the major version was not explicitly updated at the same time, **the release will fail**.
-
-If you rather want to automatically release major versions,
-use `minMajorVersion` instead of `majorVersion` and breaking changes will now increase the major version:
-
-```js
-minMajorVersion: 1
-```
-
-In the initial development phase of major version zero, breaking changes will never fail the release and instead increase the *minor* version (see above).
-
-## Release Branches
-
-You can release multiple major versions from different branches at the same time through the `releaseBranches` option.
-A separate workflow will be created for each release branch to publish the commits to this branch.
-
-Each release branch must be associated with a different version. 
-
-Normally it is sufficient to specify only `majorVersion`. If fixes to an earlier minor version should be released, `minorVersion` can also be specified.
-
-```js
-releaseBranches: {
-  '2.0': {
-    majorVersion: 2,
-    minorVersion: 0,
-  },
-  '2.x': {
-    majorVersion: 2,
-  },
-  '3.x': {
-    majorVersion: 3,
-    prerelease: 'beta',
-  },
-}
-```
-
-## Release Triggers
-
-If the project type supports it, then you can specify a `releaseTrigger`. You can use this to control whether
-or not your releases are automated as well as any unique artifacts associated with releases such as project-level
-changelogs.
-
-```js
-releaseTrigger: ReleaseTrigger.scheduled({ schedule: '0 17 * * *' }),
-```
-
-## Selective Releases
-
-It is possible to only bump the version on a subset of commits.
-For example you could only release a new version for every feature and fix that was added to the repo.
-
-```js
-releasableCommits: ReleasableCommits.featuresAndFixes(),
-```
-
-This check only runs according to the release trigger, but serves as an additional check to not create unnecessary releases.
-
-A custom check can be implemented `ReleasableCommits.exec()`.
-This command should return a list of commit hashes that are considered releasable.
-I.e. to not not bump the version, the command must print nothing and exit successfully.
-
-```js
-releasableCommits: ReleasableCommits.exec("./custom-script.sh"),
-```
-
-## Manual Releases
-
-If you don't want projen to automatically release your project, you can configure a manual release trigger:
-
-```js
-releaseTrigger: ReleaseTrigger.manual(),
-```
-
-This will create a `release` task. Run it locally (`projen release`) to cut a release. It will build the project and create releasable artifacts inside the `dist` directory.
-
-It will also trigger a `publish:git` task. This task does
-manage a project-level changelog, commit any changes, tag the release, and push any commits and tags to the remote repository.
-
-The command used for pushing can be customized by specifying
-`gitPushCommand`. Set to an empty string to disable pushing entirely.
-
-### Publishing modules for manual releases
-
-With manual releases, projen will *not* automatically publish packages to their respective package repositories.
-You are expected to publish release artifacts from the `dist` directory manually.
-
-Please note that the repository itself will **not** be a releasable state. Publishing anything else but the release artifacts from `dist`, will fail.
-
-For example in a Node.js project, you might run:
-
-- `projen release` *(runs tests & builds a releasable artifact)*
-- `npm publish dist/js/my-package-1.2.3.tgz`
-
-Or for a multi language jsii project, the necessary steps could look something like:
-
-- `projen release`
-- `npx -p publib@latest publib-npm`
-- `npx -p publib@latest publib-pypi`
-- `npx -p publib@latest publib-nuget`
-
-It is also your responsibility to ensure credentials are setup and available for each package repository published to.
-
-## FAQ
-
-### How can I force a different version?
-
-You may be adopting projen in a project that has already been published to previous versions.
-Projen uses tags to determine the version to start with before bumping according to the rules previously mentioned.
-
-You can force the base version number by adding a tag to your repo. For example, if the latest version of your project is 1.2.3, then add a tag to your main branch of `v1.2.3`.
-The next time the release workflow runs, it will bump from version 1.2.3.
-As explained above, this is based on the conventional commits so the next release will either be 1.2.4, 1.3.0, or 2.0.0 on a breaking change.
-
-### Can I change the format of the release tag?
-
-Yes, it is possible to change the tag prefix:
-
-```js
-releaseTagPrefix: 'stable/'
-```
-
-Please note that this also changes the behavior of finding existing tags and projen will now be looking for tags like `stable/1.2.3` to determine the current version.
-If you are migrating to a new tag format, make sure to re-tag at least the current version with the new format.
-
-The default prefix for release tags is `v*`. So if `releaseTagPrefix` is not defined in your `.projenrc.js` configuration you must define your tags as `v1.0.0`, `v2.0.0.0` and so on.
-
-### Why is the version in `package.json` set to `0.0.0`?
-
-Projen uses tags to keep track of the current version of the project.
-While Node.js packages natively track theirs versions in `package.json`, not all languages supported by projen provide a mechanism like this.
-Consequently projen uses git tags as a mechanism that is independent of any target language.
-To convey this message, the version in `package.json` is kept at `0.0.0`.
-
-Additionally, Node.js packages are often published directly by running `npm publish` in the root of the repository.
-This does not work in projen.
-Instead, projen requires you to run `projen release` to create releasable artifacts and manually publish these artifacts.
-
-### Can I do a manual one-off prerelease?
-
-If you wanted to generate a manual prerelease you can set the `PRERELEASE` environment variable.
-
-For example in a Node.js project, you might run:
-
-- `PRERELEASE=beta projen release` *(runs tests & builds a releasable artifact)*
-- `npm publish dist/js/my-package-1.2.3-beta.0.tgz`
-
-Make sure to also read the [Manual Releases](#manual-releases) section above.

package/docs/subproject.md

@@ -1,37 +0,0 @@
-# Subprojects
-
-* Pass a project to the `parent` prop
-* `outdir` must be specified in project props for a subproject
-
-## Example Subproject
-
-```js
-// .projenrc.js
-
-const { AwsCdkTypeScriptApp, web } = require('projen');
-
-const nextProject = new web.NextJsProject({
-  name: 'my-frontend'
-});
-
-nextProject.synth();
-
-const pipelineProject = new AwsCdkTypeScriptApp({
-  name: 'my-frontend-pipeline',
-  parent: nextProject,
-  outdir: 'pipeline',
-
-  cdkVersion: '1.78.0',
-  cdkDependencies: [
-    '@aws-cdk/aws-cloudfront',
-    '@aws-cdk/aws-s3',
-    '@aws-cdk/aws-s3-deployment',
-    '@aws-cdk/core'
-  ]
-});
-
-pipelineProject.synth();
-```
-
-By default, GitHub workflows will not be created for subprojects since config
-files in `.github/` only work if they are in the root directory.

package/docs/tasks.md

@@ -1,211 +0,0 @@
-# Tasks
-
-Tasks are a project-level feature to define a project command system backed by
-shell scripts. Tasks are used to implement development workflows and are
-accessible through the projen CLI as subcommands.
-
-The following example defines a task named "hello" which executes the shell
-command `echo hello, world!`:
-
-```js
-const hello = project.addTask('hello');
-hello.exec('echo hello, world!');
-```
-
-Run `pj` and the task will be available in the CLI:
-
-```shell
-$ projen hello
-🤖 hello | echo hello, world!
-hello, world!
-```
-
-You can also define some metadata and the first exec step declaratively:
-
-```js
-const projen = require('projen');
-
-const hello = project.addTask('hello', {
-  description: 'say hello',
-  category: projen.tasks.TaskCategory.TEST,
-  exec: 'echo hello, world!'
-});
-```
-
-## Steps
-
-Tasks can include any number of _steps_:
-
-```ts
-hello.exec('echo step number 2');
-
-// a name can be added to a step if desired
-hello.exec('echo foo bar', { name: 'print the text "foo bar"' });
-```
-
-The `--inspect` option can be used to display the contents of a task:
-
-```shell
-$ projen hello --inspect
-echo hello, world!
-echo step number 2
-echo foo bar
-```
-
-If a step fails, the task will fail and all subsequent steps will not be
-executed.
-
-You can also add steps to the beginning of a task:
-
-```ts
-const hello = project.addTask('hello');
-hello.exec('echo hello');
-hello.prepend('echo world');
-```
-
-Then:
-
-```shell
-$ projen hello 2> /dev/null
-world
-hello
-```
-
-## Subtasks
-
-Tasks can also spawn sub-tasks as a step:
-
-```ts
-const world = project.addTask('world');
-world.exec('echo world!');
-
-const hello = project.addTask('hello');
-hello.exec('echo hello');
-hello.spawn(world);
-```
-
-The output will be:
-
-```shell
-$ projen hello
-🤖 hello | echo hello
-hello
-🤖 hello » world | echo world!
-world!
-
-$ projen hello --inspect
-echo hello
-world:
-   echo world!
-```
-
-## Environment
-
-Environment variables can be defined at the project level (for all tasks), the task level, or the task step level:
-
-```ts
-project.tasks.addEnvironment('FOO', 'hello');
-
-const hello = project.addTask('hello');
-hello.env('BAR', 'beautiful');
-hello.exec('echo $FOO, $BAR $BAZ!', { env: { BAZ: 'world' } });
-```
-
-Then:
-
-```shell
-$ projen hello
-🤖 hello | echo $FOO, $BAR $BAZ!
-hello, beautiful world!
-```
-
-You can also evaluate environment variable values from a shell command:
-
-```ts
-const hello = project.addTask('hello');
-hello.env('TIME', '$(date)');
-hello.exec('echo current time is $TIME');
-```
-
-Then:
-
-```shell
-$ projen hello
-🤖 hello | echo current time is $TIME
-current time is Tue Dec 1 09:32:33 IST 2020
-```
-
-## Conditions
-
-The `condition` option includes a command that determines if the task is
-executed. If the command exits successfully (with a zero exit code), steps will
-be executed. Otherwise, the task will be skipped (successfully).
-
-```ts
-const hello = project.addTask('hello', {
-  condition: '[ -n "$CI" ]', // only execute if the CI environment variable is defined
-  exec: 'echo running in a CI environment'
-});
-```
-
-Then:
-
-```shell
-$ projen hello
-🤖 hello | condition: [ -n "$CI" ]
-🤖 hello | condition exited with non-zero - skipping
-
-$ CI=1 projen hello
-🤖 hello | condition: [ -n "$CI" ]
-🤖 hello | echo running in a CI environment
-running in a CI environment
-```
-
-The `condition` option can also be specified on individual task steps, for more
-granular control over task execution behavior:
-
-```ts
-const hello = project.addTask('hello', {
-  steps: [
-    { exec: 'running in a CI environment', condition: '[ -n "$CI" ]' },
-    { exec: 'not running in a CI environment', condition: '[ ! -n "$CI" ]' }
-  ]
-});
-```
-
-Then:
-
-```shell
-$ projen hello
-🤖 hello | condition: [ -n "$CI" ]
-🤖 hello | condition exited with non-zero - skipping
-🤖 hello | condition: [ ! -n "$CI" ]
-🤖 hello | echo not running in a CI environment
-not running in a CI environment
-
-$ CI=1 projen hello
-🤖 hello | condition: [ -n "$CI" ]
-🤖 hello | echo running in a CI environment
-running in a CI environment
-🤖 hello | condition: [ ! -n "$CI" ]
-🤖 hello | condition exited with non-zero - skipping
-```
-
-## Tasks as npm scripts
-
-By default, npm scripts in `NodeProject`s (or derivatives) are implemented by delegating the
-command to the projen CLI:
-
-```json
-{
-  "scripts": {
-    "compile": "npx projen compile"
-  }
-}
-```
-
-This means that when `yarn compile` or `npm run compile` are executed, the
-projen CLI will be invoked and the task will be executed.
-
-You can see a list of all steps in a task from the command line by passing
-the `--inspect` flag, e.g. `yarn compile --inspect`.