From 61026e129aec8a93cff9f8a4c7b3b5dce45ca67a Mon Sep 17 00:00:00 2001 From: Kenny Gatdula Date: Sun, 9 Jun 2024 12:24:57 -0400 Subject: [PATCH] feat: add support for github issue templates --- docs/api/github.md | 343 +++++++++++++++++++++++++++++++++++ src/github/issue-template.ts | 42 ++--- 2 files changed, 361 insertions(+), 24 deletions(-) diff --git a/docs/api/github.md b/docs/api/github.md index fdbe34706e78..222d94cd52fb 100644 --- a/docs/api/github.md +++ b/docs/api/github.md @@ -2349,6 +2349,171 @@ contexts. --- +### IssueTemplate + +Generates Issue Templates for GitHub repositories see {@link https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests}. + +#### Initializers + +```typescript +import { github } from 'projen' + +new github.IssueTemplate(github: GitHub, options: IssueTemplateOptions) +``` + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| github | GitHub | *No description.* | +| options | IssueTemplateOptions | *No description.* | + +--- + +##### `github`Required + +- *Type:* GitHub + +--- + +##### `options`Required + +- *Type:* IssueTemplateOptions + +--- + +#### Methods + +| **Name** | **Description** | +| --- | --- | +| toString | Returns a string representation of this construct. | +| postSynthesize | Called after synthesis. | +| preSynthesize | Called before synthesis. | +| synthesize | Synthesizes files to the project output directory. | + +--- + +##### `toString` + +```typescript +public toString(): string +``` + +Returns a string representation of this construct. + +##### `postSynthesize` + +```typescript +public postSynthesize(): void +``` + +Called after synthesis. + +Order is *not* guaranteed. + +##### `preSynthesize` + +```typescript +public preSynthesize(): void +``` + +Called before synthesis. + +##### `synthesize` + +```typescript +public synthesize(): void +``` + +Synthesizes files to the project output directory. + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| isConstruct | Checks if `x` is a construct. | +| isComponent | Test whether the given construct is a component. | + +--- + +##### `isConstruct` + +```typescript +import { github } from 'projen' + +github.IssueTemplate.isConstruct(x: any) +``` + +Checks if `x` is a construct. + +Use this method instead of `instanceof` to properly detect `Construct` +instances, even when the construct library is symlinked. + +Explanation: in JavaScript, multiple copies of the `constructs` library on +disk are seen as independent, completely different libraries. As a +consequence, the class `Construct` in each copy of the `constructs` library +is seen as a different class, and an instance of one class will not test as +`instanceof` the other class. `npm install` will not create installations +like this, but users may manually symlink construct libraries together or +use a monorepo tool: in those cases, multiple copies of the `constructs` +library can be accidentally installed, and `instanceof` will behave +unpredictably. It is safest to avoid using `instanceof`, and using +this type-testing method instead. + +###### `x`Required + +- *Type:* any + +Any object. + +--- + +##### `isComponent` + +```typescript +import { github } from 'projen' + +github.IssueTemplate.isComponent(x: any) +``` + +Test whether the given construct is a component. + +###### `x`Required + +- *Type:* any + +--- + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| node | constructs.Node | The tree node. | +| project | projen.Project | *No description.* | + +--- + +##### `node`Required + +```typescript +public readonly node: Node; +``` + +- *Type:* constructs.Node + +The tree node. + +--- + +##### `project`Required + +```typescript +public readonly project: Project; +``` + +- *Type:* projen.Project + +--- + + ### Mergify #### Initializers @@ -4629,6 +4794,62 @@ The name of the artifact the patch is stored as. --- +### ContactLinks + +#### Initializer + +```typescript +import { github } from 'projen' + +const contactLinks: github.ContactLinks = { ... } +``` + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| about | string | A brief description of the contact link. | +| name | string | The name of the contact link. | +| url | string | The URL of the contact link. | + +--- + +##### `about`Required + +```typescript +public readonly about: string; +``` + +- *Type:* string + +A brief description of the contact link. + +--- + +##### `name`Required + +```typescript +public readonly name: string; +``` + +- *Type:* string + +The name of the contact link. + +--- + +##### `url`Required + +```typescript +public readonly url: string; +``` + +- *Type:* string + +The URL of the contact link. + +--- + ### ContributorStatementOptions Options for requiring a contributor statement on Pull Requests. @@ -6392,6 +6613,128 @@ The name of the user. --- +### IssueTemplateConfigOptions + +Options for configuring issue templates in a repository. + +> [{@link https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser}]({@link https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser}) + +#### Initializer + +```typescript +import { github } from 'projen' + +const issueTemplateConfigOptions: github.IssueTemplateConfigOptions = { ... } +``` + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| blankIssuesEnabled | boolean | Indicates whether blank issues (issues without a template) are allowed. | +| contactLinks | ContactLinks[] | An array of contact links to display in the issue template chooser. | + +--- + +##### `blankIssuesEnabled`Optional + +```typescript +public readonly blankIssuesEnabled: boolean; +``` + +- *Type:* boolean + +Indicates whether blank issues (issues without a template) are allowed. + +--- + +##### `contactLinks`Optional + +```typescript +public readonly contactLinks: ContactLinks[]; +``` + +- *Type:* ContactLinks[] + +An array of contact links to display in the issue template chooser. + +--- + +### IssueTemplateOptions + +Options for `IssueTemplate`. + +#### Initializer + +```typescript +import { github } from 'projen' + +const issueTemplateOptions: github.IssueTemplateOptions = { ... } +``` + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| templates | {[ key: string ]: string} | An array of issue template file names and their contents. | +| configOptions | IssueTemplateConfigOptions | Configuration options for the config.yml file. Only applicable if includeConfig is true. | +| includeConfig | boolean | Whether to include a config.yml file for configuring the issue template chooser. Defaults to false. | +| templatePath | string | The path within the repository where the issue templates should be created. | + +--- + +##### `templates`Required + +```typescript +public readonly templates: {[ key: string ]: string}; +``` + +- *Type:* {[ key: string ]: string} + +An array of issue template file names and their contents. + +The file names should include the extension (.md or .yml). + +--- + +##### `configOptions`Optional + +```typescript +public readonly configOptions: IssueTemplateConfigOptions; +``` + +- *Type:* IssueTemplateConfigOptions + +Configuration options for the config.yml file. Only applicable if includeConfig is true. + +--- + +##### `includeConfig`Optional + +```typescript +public readonly includeConfig: boolean; +``` + +- *Type:* boolean + +Whether to include a config.yml file for configuring the issue template chooser. Defaults to false. + +--- + +##### `templatePath`Optional + +```typescript +public readonly templatePath: string; +``` + +- *Type:* string + +The path within the repository where the issue templates should be created. + +Defaults to '.github/ISSUE_TEMPLATE'. + +--- + ### MergifyConditionalOperator The Mergify conditional operators that can be used are: `or` and `and`. diff --git a/src/github/issue-template.ts b/src/github/issue-template.ts index 063d1c76e579..c1cdf53abbac 100644 --- a/src/github/issue-template.ts +++ b/src/github/issue-template.ts @@ -4,6 +4,23 @@ import { Component } from "../component"; import { TextFile } from "../textfile"; import { YamlFile } from "../yaml"; +export interface ContactLinks { + /** + * The name of the contact link. + */ + readonly name: string; + + /** + * The URL of the contact link. + */ + readonly url: string; + + /** + * A brief description of the contact link. + */ + readonly about: string; +} + /** * Options for configuring issue templates in a repository. * @@ -21,30 +38,8 @@ export interface IssueTemplateConfigOptions { /** * An array of contact links to display in the issue template chooser. * - * @type {Array<{ name: string; url: string; about: string }>} [contactLinks=[]] */ - readonly contactLinks?: { - /** - * The name of the contact link. - * - * @type {string} - */ - name: string; - - /** - * The URL of the contact link. - * - * @type {string} - */ - url: string; - - /** - * A brief description of the contact link. - * - * @type {string} - */ - about: string; - }[]; + readonly contactLinks?: ContactLinks[]; } /** @@ -74,7 +69,6 @@ export interface IssueTemplateOptions { * Only applicable if includeConfig is true. */ readonly configOptions?: IssueTemplateConfigOptions; - } /**