projen 0.0.0

package/docs/java.md

@@ -0,0 +1,213 @@
+# Java Projects
+
+To create a new Java project, use `projen new java`:
+
+```shell
+$ projen new java --group-id org.acme --artifact-id hello-maven
+```
+
+This will synthesize a standard Maven project directory structure with a
+`pom.xml` file and some sample code:
+
+```shell
+├── pom.xml
+└── src
+    ├── main/java/org/acme
+    │   └── Main.java
+    └── test/java/org/acme
+         └── MyTest.java
+```
+
+At this point, you should be able to now simply run `projen build` to build your
+project:
+
+```shell
+$ projen build
+[INFO] BUILD SUCCESS
+```
+
+> Since this is a standard Maven project, so you can also use `mvn package`,
+> `mvn test`, etc. IDEs should also feel at home with this project.
+
+The `projen new` command will also generate a `.projenrc.js` file which includes
+the definition of your project with any options you specified in the command
+line:
+
+```js
+const { java } = require('projen');
+
+const project = new java.JavaProject({
+  artifactId: 'hello-maven',
+  groupId: 'org.acme',
+  name: 'hello-maven',
+  version: '0.1.0',
+});
+
+project.synth();
+```
+
+It is possible to create your projenrc file in java. In the future, this will be
+the default, but at the moment you need to add some configuration. See the
+[`projenrc.java`](#projenrcjava) section for details.
+
+To modify your project definitions, edit `.projenrc.js` and run `projen` again
+to re-synthesize your project. The following sections describe the various features of Java projects.
+
+## Versioning
+
+You can set the project version through the `version` options:
+
+```ts
+const project = new java.MavenProject({
+  version: '1.2.3'
+};
+```
+
+## Project Metadata
+
+You can specify additional metadata for your project by passing options to the
+constructor of `MavenProject`. For example, let's add a description and a URL
+for your project:
+
+```ts
+const project = new java.JavaProject({
+  // ...
+
+  description: 'My first java projen project',
+  url: 'https://github.com/projen/projen'
+});
+```
+
+See the API reference for [PomOptions](../API.md#projen-java-pomoptions) for a
+detailed list of options.
+
+## Dependencies
+
+Java projects have three types of supported dependencies:
+
+1. Runtime dependencies (or just "dependencies").
+2. Test dependencies
+3. Maven plugins (modeled as build dependencies).
+
+You can define dependencies when defining the project itself:
+
+```ts
+const project = new JavaProject({
+  deps: [
+    'software.amazon.awscdk/core@^1.2.3',
+    'software.amazon.awscdk/aws-s3@^1',
+  ]
+});
+```
+
+Or using the APIs:
+
+```ts
+project.addTestDependency('org.assertj/assertj-core@^3');
+```
+
+Notice the syntax for dependencies:
+
+```text
+<groupId>/<artifactId>[@version]
+```
+
+Where `groupID` and `artifactId` are the Maven coordinates and `version` is the
+[semantic version requirement](https://semver.org) for the dependency. The
+semver syntax will be converted to POM syntax. For example, `^3.1.0` will be
+converted to `[3.1.0,4.0.0)`.
+
+## `projenrc.java`
+
+It is possible to write your projenrc file in Java. In the future this will be
+the default for Java projects, but at the moment this needs to be enabled when
+the project is created:
+
+```shell
+$ projen new java --projenrc-java
+```
+
+Or set through:
+
+```ts
+new java.JavaProject({
+  // ...
+  projenrcJava: true
+});
+```
+
+Then, create a file `src/test/java/projenrc.java` that looks like this:
+
+```java
+import org.projen.java.JavaProject;
+import org.projen.java.JavaProjectOptions;
+
+public class projenrc {
+    public static void main(String[] args) {
+        JavaProject project = new JavaProject(JavaProjectOptions.builder()
+            .name("my-app")
+            .groupId("org.acme")
+            .artifactId("my-app")
+            .version("1.0.0")
+            .build());
+    
+        project.synth();
+    }
+}
+```
+
+In order to synthesize, run: `pj synth`, which will compile your test code and
+execute this program.
+
+By default, `projenrc.java` is placed under the `test` scope (and
+`io.github.cdklabs/projen` test dependency is added). This ensures that
+application code does not take a dependency on projen code. You can change this
+behavior by setting the `testScope` option to `false`.
+
+## Maven Plugins
+
+You can add Maven build plugins to your project using `project.addPlugin()`:
+
+```ts
+project.addPlugin('org.apache.maven.plugins/maven-compiler-plugin@3.8.1', {
+  configuration: {
+    source: '1.8',
+    target: '1.8',
+  },
+});
+```
+
+## Unit Testing with JUnit
+
+The `JUnit` component adds support for writing Java tests with
+[JUnit](https://junit.org/). The component will add the required test
+dependencies to your POM file.
+
+Test sources are placed under `src/test` and can be executed via `mvn test` or
+`projen test` (same).
+
+To disable JUnit tests, set `junit: false` when you define the `MavenProject`.
+
+## Packaging
+
+Java projects include definitionds for producing an output that is
+ready-to-publish to Maven using tools like
+[jsii-release](https://www.npmjs.com/package/jsii-release). In future versions
+of projen we will also support auto-publishing through CI/CD.
+
+The packaging component adds a `package` task which uses `mvn deploy` to create
+a local maven directory with artifacts that can be uploaded to a Maven
+repository such as Maven Central, CodeArtifact or GitHub Packages.
+
+By default, packages includes *javadocs* and *sources*. Those can be disabled
+through `packagingOptions`.
+
+## Publishing
+
+TBD.
+
+> Publishing to Maven is still not supported output of the box. Since the
+> package output of `JavaProject` is compatible with
+> [jsii-release](https://www.npmjs.com/package/jsii-release), and we already
+> release to Maven from jsii projects, it should be possible to reuse quite a
+> lot.

package/docs/node.md

@@ -0,0 +1,20 @@
+# Node.js Projects
+
+This topic describes all the features of `NodeProject` projects and their
+derivatives.
+
+## Development Workflow
+
+TODO
+
+## Dependencies
+
+TODO
+
+## Pull Request Builds (CI)
+
+TODO
+
+## Releases (CI/CD)
+
+TODO

package/docs/programmatic-api.md

@@ -0,0 +1,56 @@
+# Programmatic API
+
+Projen exposes a programmatic API that allows you to create new projects through
+code instead of the regular CLI command `npx projen new`. This allows projen to
+be used to create new projects within scripts and other contexts.
+
+## Example
+
+```js
+const { Projects } = require('projen');
+
+Projects.createProject({
+  dir: '/path/to/mydir',
+  projectFqn: 'projen.TypeScriptProject',
+  projectOptions: {
+    name: 'my-test-project',
+    defaultReleaseBranch: 'main',
+    projenrcTs: true,
+    eslintOptions: {
+      dirs: ['src', 'test'],
+      prettier: true,
+      aliasMap: {
+        '@src': './src',
+        '@components': './src/components',
+      },
+    },
+  },
+  post: false,
+  // synth: true (default)
+  // optionHints: 'featured' (default)
+});
+```
+
+This script creates a new TypeScript project at `/path/to/mydir` in my file
+system. The `.projenrc.ts` file it generates comes pre-included with options
+specified, including complex values for fields that cannot normally be provided
+through the CLI, like `eslintOptions` (because the field requires an object
+value).
+
+In the above example, the provided option `post: false` was also added to
+disable post-installation steps such as installing NPM dependencies.
+
+> **Note:** It is important that you provide all fields that are required by the
+project type, otherwise the project may not synthesize properly.
+
+It is also possible to use this for installing external project types.
+Currently, this requires you to install the package so that it can be used by
+projen.
+
+```js
+Projects.createProject({
+  // ...
+  projectFqn: '@myorg/my-package.MyJsiiProject',
+});
+```
+

package/docs/publisher.md

@@ -0,0 +1,148 @@
+# Publishing Modules
+
+The `Publisher` component supports publishing modules to various package
+managers. It is designed to be attached to a GitHub workflow that takes care of
+building the module and uploading a "ready to publish" artifact.
+
+> This component is utilized in `NodeProject` and `JsiiProject` to publish modules.
+
+Supported package managers:
+
+- npm
+- Maven
+- PyPI
+- NuGet
+- Go (GitHub)
+
+This is how a publisher is initialized:
+
+```ts
+const publisher = new Publisher(project, {
+  workflow: releaseWorkflow,
+  buildJobId: 'my-build-job',
+  artifactName: 'dist',
+});
+```
+
+`workflow` is a `GithubWorkflow` with at least one job (in this case named
+`my-build-job`) which is responsible to build the code and upload a GitHub
+workflows artifact (named `dist` in this case) which will then be consumed by
+the publishing jobs.
+
+This component is opinionated about the subdirectory structure of the artifact:
+
+|Subdirectory|Type|Contents|
+|-|-|-|
+|`js/*.tgz`|NPM|npm tarballs
+|`dotnet/*.nupkg`|NuGet|Nuget packages
+|`python/*.whl`|PyPI|Python wheels
+|`go/**/go.mod`|Go|Go modules. Each subdirectory should have its own `go.mod` file
+|`java/**`|Maven|Maven artifacts in local repository structure
+
+Then, you should call `publishToXxx` to add publishing jobs to the workflow:
+
+For example:
+
+```ts
+publisher.publishToNuGet();
+publisher.publishToMaven(/* options */);
+// ...
+```
+
+See API reference for options for each target.
+
+## Customizing Publishing Jobs
+
+You can customize the publishing jobs by specifying `prePublishSteps` which is a
+set of GitHub workflow steps to be executed before publishing. The
+`publishTools` option can be used to setup the toolchain required for the
+publishing job.
+
+For example:
+
+```ts
+publisher.publishToNuGet({
+  publishTools: { dotnet: { version: '5.x' } },
+  prePublishSteps: [
+    { run: 'dotnet ...' }
+  ]
+});
+```
+
+## Publishing to GitHub Packages
+
+Some targets come with dynamic defaults that support GitHub Packages.
+If the respective registry URL is detected to be GitHub, other relevant options will automatically be set to fitting values.
+It will also ensure that the workflow token has write permissions for Packages.
+
+**npm**
+
+```ts
+publisher.publishToNpm({
+  registry: 'npm.pkg.github.com'
+  // also sets npmTokenSecret
+})
+```
+
+**Maven**
+
+```ts
+publisher.publishToMaven({
+  mavenRepositoryUrl: 'https://maven.pkg.github.com/USER/REPO'
+  // also sets mavenServerId, mavenUsername, mavenPassword
+  // disables mavenGpgPrivateKeySecret, mavenGpgPrivateKeyPassphrase, mavenStagingProfileId
+})
+```
+
+## Publishing to AWS CodeArtifact
+
+The NPM target comes with dynamic defaults that support AWS CodeArtifact.
+If the respective registry URL is detected to be AWS CodeArtifact, other relevant options will automatically be set to fitting values.
+The authentication will done using [AWS CLI](https://docs.aws.amazon.com/codeartifact/latest/ug/tokens-authentication.html). It is neccessary to provide AWS IAM CLI `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` in GitHub Secrets.
+
+**npm**
+
+```ts
+publisher.publishToNpm({ 
+  registry: 'my-domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/my_repo/',
+});
+```
+
+The names of the GitHub Secrets can be overridden if different names should be used.
+
+```ts
+publisher.publishToNpm({ 
+  registry: 'my-domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/my_repo/',
+  codeArtifactOptions: {
+    accessKeyIdSecret: 'CUSTOM_AWS_ACCESS_KEY_ID',
+    secretAccessKeySecret: 'CUSTOM_AWS_SECRET_ACCESS_KEY',
+  },
+});
+```
+
+## Handling Failures
+
+You can instruct the publisher to create GitHub issues for publish failures:
+
+```ts
+const publisher = new Publisher(project, {
+  workflow: releaseWorkflow,
+  buildJobId: 'my-build-job',
+  artifactName: 'dist',
+  issueOnFailure: true,
+  failureIssueLabel: 'failed-release'
+});
+```
+
+This will create an issue labeled with the `failed-release` label for every individual failed publish task.
+For example, if Nuget publishing failed for a specific version, it will create an issue titled *Publishing v1.0.4 to Nuget gallery failed*.
+
+This can be helpful to keep track of failed releases as well as integrate with third-party ticketing systems by querying issues labeled with `failed-release`.
+
+## Dry run
+
+If you wish to completely disable publishing, you can enable the `dryRun` option on
+`Publisher` or `publishDryRun` on the project.
+
+This will cause all publishing tasks and jobs to just print the publishing
+command but not actually publish.

package/docs/python.md

@@ -0,0 +1,167 @@
+# 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.js` file which includes
+the definition of your project with any options you specified in the command
+line:
+
+```js
+const { python } = require('projen');
+
+const project = new python.PythonProject({
+  jsiiFqn: "projen.python.PythonProject",
+  name: 'my-project',
+  moduleName: 'my_project',
+});
+
+project.synth();
+```
+
+> At this point, projenrc is in JavaScript, but in the future we plan to allow
+> specifying your project definitions in python.
+
+To modify your project definitions, edit `.projenrc.js` 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:
+
+```js
+const project = new python.PythonProject({
+  ...
+  projectType: ProjectType.LIB
+});
+```
+
+But these can be swapped out as needed by using the provided flags, for example:
+
+```js
+const project = new python.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:
+
+```ts
+const project = new python.PythonProject({
+  deps: [
+    'Django@3.1.5',
+    'aws-cdk.core', // implies "@*"
+  ],
+  testDeps: [
+    'hypothesis@^6.0.3',
+  ],
+});
+```
+
+Or using the APIs:
+
+```ts
+project.addTestDependency('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:
+
+* Poetry requires the `python` version to be specified as a dependency e.g. `python@^3.7,<=3.9`.
+  When not specified, projen will set it to a default value of `python@^3.6`.
+* 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`
+
+TBD
+
+> In the future, it will be possible to write your projenrc file in Python.
+
+## 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

@@ -0,0 +1,71 @@
+# Releases and Versioning
+
+Projen takes care of managing versioning and releases of your project. A project starts with version `0.0.0` and the version 
+is "bumped" automatically in every release, based on the contents of the release.
+
+The content of the release is determined by listing all the commits since the last release and parsing them according to
+[conventional commits spec](https://www.conventionalcommits.org/en/v1.0.0/). If the release only includes `fix` commits, then
+the new version will be a patch version. If the release includes `feat` commits, then the new version will be a minor version.
+
+If the release includes breaking changes and the major version was not explicitly updated in projenrc (see below), the release will fail.
+
+## Major Versions
+
+Each branch is associated with a major version. By default, the major version of the default branch is `0`. 
+
+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
+```
+
+It is possible to release the same major version to different branches by specifying a prefix that is applied to all tags for a particular branch.
+
+For example:
+
+```js
+tagPrefix: 'stable/'
+```
+
+## Release Branches
+
+Our release model is based on [trunk-based development](https://trunkbaseddevelopment.com/). 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.
+
+You can add additional release branches (e.g. for different major versions) through the `releaseBranches` option. Each release branch must
+be associated with a different major version.
+
+```js
+releaseBranches: {
+  '2.x': {
+    majorVersion: 2,
+  },
+  '3.x': {
+    majorVersion: 3,
+    prerelease: true,
+  },
+}
+```
+
+## 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 * * *' }),
+```
+
+### Manual Releases
+
+```js
+releaseTrigger: ReleaseTrigger.manual(),
+```
+
+Using manual releases disables the generation of the github release workflow and provides an extra
+`publish:git` task which is triggered as part of the `release` task. `publish:git` will manage a
+project-level changelog, commit any changes, tag the release, and push any commits and tags to
+remote.