projen 0.76.5 → 0.76.7

package/docs/java.md

@@ -1,213 +0,0 @@
-# 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/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

@@ -1,150 +0,0 @@
-# Node.js Projects
-
-This topic describes all the features of `NodeProject` projects and their
-derivatives.
-
-## Node versioning
-
-You can specify the minimum version of node that your project supports, and the version of node used in GitHub workflows:
-
-```js
-const project = new javascript.NodeProject({
-  // ...
-  minNodeVersion: '16.0.0',
-  workflowNodeVersion: '16.1.0', // defaults to minNodeVersion
-});
-```
-
-## Development Workflow
-
-TODO
-
-## GitHub workflows
-
-Node.js projects with GitHub enabled come bundled with components for running
-build workflows on every pull request, automatically upgrading dependencies, and
-other conveniences.
-
-For more general information about managing GitHub configuration, check out
-[GitHub](./github.md).
-
-## Dependencies
-
-See [Dependencies](#dependencies) for general information about how dependencies
-are managed by projen, and how to add new dependencies to your project. By
-default, every Node.js project includes a `Dependencies` component which will
-manage the dependencies in `package.json`.
-
-When a dependency is managed by projen, it gets added to `package.json` and will
-automatically installed after running `npx projen`. Packages will be installed
-according to the package manager being used. This can be configured:
-
-```ts
-const project = new javascript.NodeProject({
-  // ...
-  packageManager: javascript.NodePackageManager.YARN_CLASSIC, // or NPM, PNPM, etc.
-});
-```
-
-Any dependencies without specific version ranges set (such as `react` or
-`react@*`) will given a version range in `package.json` so that future package
-upgrades and changes to the generated lockfiles such as `package-lock.json` or
-`yarn.lock` will follow semver.
-
-A list of all dependencies managed by projen is also reported in
-`.projen/deps.json`.
-
-### Dependency upgrades
-
-Node.js projects include an `upgrade` [task] and `upgrade.yml` [GitHub workflow]
-that updates node dependencies following semver. The GitHub workflow will
-automatically run once a day, and can also be automatically approved for
-hands-off dependency managed.
-
-> If you want to upgrade a dependency to a new **major** version (with possible
-> breaking changes), you should update its version range via the projenrc file.
-
-In order to create these PRs, permissions to GitHub APIs are needed beyond those
-provided by GITHUB_TOKEN, otherwise no subsequent workflows will be triggered,
-such as the build workflow (see [create-pull-request#48] for details). Because
-of this we require, [GitHub API access] to be provided for these workflows.
-
-It's possible to create a separate workflow and task just for upgrading projen:
-
-```ts
-const project = new javascript.NodeProject({
-  depsUpgrade: true,
-  depsUpgradeOptions: {
-    exclude: ['projen'],
-  },
-});
-
-new javascript.UpgradeDependencies(project, {
-  include: ['projen'],
-  taskName: "upgrade-projen",
-  workflow: false, // or true
-  // workflowOptions: { ... }
-});
-```
-
-You can also use dependabot or renovatebot to get Pull requests on dependency updates
-
-* Dependabot:
-  ```ts
-  new javascript.NodeProject({
-    depsUpgrade: false,
-    dependabot: true,
-    // dependabotOptions: { ... }
-  })
-  ```
-* Renovatebot: 
-  ```ts
-  new javascript.NodeProject({
-    depsUpgrade: false,
-    renovatebot: true,
-    // renovatebotOptions: { ... }
-  })
-  ```
-
-[task]: ./tasks.md
-[GitHub workflow]: ./github.md#workflows
-[create-pull-request#48]: https://github.com/peter-evans/create-pull-request/issues/48
-[GitHub API access]: ./github.md#github-api-access
-
-## Pull Request Builds (CI)
-
-TODO
-
-## Releases (CI/CD)
-
-TODO
-
-## Features
-
-### Scoped Private Packages
-
-Scoped private packages can be configured in this project and its ancestors.
-
-All npm packages have a name. Some package names also have a scope. A scope follows the usual rules for package names (URL-safe characters, no leading dots or underscores). When used in package names, scopes are preceded by an @ symbol and followed by a slash, e.g. `@somescope/somepackagename`
-
-This feature supports specifying options on how package managers should access packages in each of the scopes. If no options are specified, npm or yarn will try to install scoped packages from the public npm registry.
-
-Currently, it only supports fetching packages from AWS CodeArtifact, either by directly access via credentials or by assuming a role using the specified credentials. Credentials must be provided in the CodeArtifactOptions property.
-
-Multiple scoped package options may be specified if required.
-
-example
-```js
-const { javascript } = require('projen');
-const project = new javascript.NodeProject({
-  defaultReleaseBranch: 'main',
-  name: 'my-project',
-  scopedPackagesOptions: [
-      {
-          registryUrl: '<code-artifact-registry-url>',
-          scope: '@somescope',
-      }
-  ]
-});
-project.synth();
-```

package/docs/programmatic-api.md

@@ -1,56 +0,0 @@
-# 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.typescript.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

@@ -1,148 +0,0 @@
-# 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.