Skip to content
This repository has been archived by the owner on Aug 16, 2024. It is now read-only.

Feat/81 contribution guide #124

Merged
merged 2 commits into from
Jan 22, 2024
Merged

Feat/81 contribution guide #124

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f38f822
Contribution Guide WIP
AdityaKulkarni Dec 21, 2023
6676f93
fix: minor typos
jamesrp13 Jan 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 79 additions & 12 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Please note we have a **code of conduct**, please follow it in all your interact

## Setting up for Local Development

1. Fork this repostiory.
1. Fork this repository.
2. Clone your fork.
3. Create a new branch in your local repository with the following pattern:

Expand All @@ -15,18 +15,19 @@ Please note we have a **code of conduct**, please follow it in all your interact
- For chores/the rest: `chore/[descriptive_chore_name]`

4. Install dependencies with Yarn: `yarn install`
5. Add `./node_modules/.bin` to your system's [`PATH`](https://en.wikipedia.org/wiki/PATH_(variable)), if it's not already listed.
5. Add `./node_modules/.bin` to your system's [`PATH`](<https://en.wikipedia.org/wiki/PATH_(variable)>), if it's not already listed.
6. Start building for development: `yarn dev`

### Development Scripts

| NPM Script | Description |
| --------------------------- | ----------- |
| `yarn dev` | Start building the CLI tool in development mode. |
| `yarn build` | Build the CLI tool for production. |
| `yarn clean` | Run cleaning scripts. |
| `yarn lint` | Run the linter. |
| `yarn test` | Run unit tests. |
| NPM Script | Description |
| --------------------| ------------------------------------------------|
| `yarn dev` | Start building the CLI tool in development mode.|
| `yarn build` | Build the CLI tool for production. |
| `yarn clean` | Run cleaning scripts. |
| `yarn lint` | Run the linter. |
| `yarn test` | Run unit tests. |
| `yarn template-dev` | Run development command for a specific template. Most changes will hot-reload|

## Opening a Pull Request

Expand All @@ -36,7 +37,74 @@ Please note we have a **code of conduct**, please follow it in all your interact

## Cutting a release

We use [`auto`](https://github.com/intuit/auto) as our continous delivery tool. Cutting a release is just a matter of merging to `master`. For pre-releases, you can create a `next` branch as the base for your experimental/W.I.P. feature. Please familiarize yourself with the [documentation for `auto`](https://intuit.github.io/auto/docs) if you are in a position to cut a release.
We use [`auto`](https://github.com/intuit/auto) as our continuous delivery tool. Cutting a release is just a matter of merging to `master`. For pre-releases, you can create a `next` branch as the base for your experimental/W.I.P. feature. Please familiarize yourself with the [documentation for `auto`](https://intuit.github.io/auto/docs) if you are in a position to cut a release.

## Community Templates

### Adding a new template

1. Fork the repository.
2. Create a new branch `feat/<template_name>`.
3. Create a new directory under `scaffolds` named `<template_name>`.
4. Under that, create a `<template>` directory which will contain the source code.
5. Create a `scaffold.ts` as well under the `<template_name>` directory.
6. Modify `core/utils/templateMappings.ts` accordingly to include the new template.
7. If your project uses `.env`, make sure it is named as `.env.example`

### Updating existing template

1. If there are changes in the template source itself, edit the template from `scaffolds/<template_name>/template`.
2. If there are changes in the scaffold declaration, edit the `scaffolds/<template_name>/scaffold.ts`.
3. Change `core/utils/templateMappings.ts` accordingly to incorporate new changes.

### Adding / Updating prompts

Magic CLI uses `enquirer` package to create prompts for the templates.

#### Adding a new prompt

1. Create the `<PromptNamespace>` in `scaffolds/prompts.ts`
2. Make sure your prompt includes an exported type named `Data` and `flags` object. This will be used to show `--help` for the template specific options.
3. If your prompt needs questions, export those questions in respective functions.

Here's an example:

```ts
export namespace GreetingPrompt {
//This type will be used in `scaffold.ts` to determine the type of data on which the template depends on
export type Data = {
Name: string;
};

//This prompt will be called if the data is not provided in flag arguments when calling the CLI
export const askName = async () =>
new Input({
name: 'Name',
message: 'What is your name?',
initial: 'John Doe',
}).run();

//Used for declaring flags, their aliases and providing help description
export const flags: Flags<Partial<Data>> = {
Name: {
type: String,
description: 'Your name.',
},
};
}
```

#### Updating a prompt

Edit the `scaffolds/prompts.ts` to update the desired prompt.

> Update the `scaffolds/<template_name>/scaffold.ts` files which depend on the newly added / edited templates appropriately. Also, make necessary changes to `core/utils/templateMappings.ts`.

### EJS Templates

Magic CLI uses `ejs` package to embed Javascript templates in the code which needs to change dynamically based on CLI inputs. If your template uses EJS embedding, make sure to add default values for your template in the `scaffolds/dev-data.ts` file. Make sure that the properties in the default valies matches that of the flags on which your template depends on.

You can run and test the template with `npm run template-dev <template-name>` script to make sure that the template is working as expected.

## Contributor Covenant Code of Conduct

Expand Down Expand Up @@ -140,7 +208,7 @@ Violating these terms may lead to a permanent ban.
#### 4. Permanent Ban

**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.

**Consequence**: A permanent ban from any sort of public interaction within
Expand All @@ -158,4 +226,3 @@ enforcement ladder](https://github.com/mozilla/diversity).
For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.

Loading