Skip to content

Commit

Permalink
first version of docs content is finished
Browse files Browse the repository at this point in the history
  • Loading branch information
km1chno committed Sep 18, 2024
1 parent ce05414 commit 1afe949
Show file tree
Hide file tree
Showing 5 changed files with 90 additions and 50 deletions.
37 changes: 5 additions & 32 deletions docs/docs-site/docs/aux-workflows/lookup-cached-debug-build.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -72,38 +72,11 @@ a hash string of your native code (called _fingerprint_). It then checks whether

#### build-debug-android

The following diagram represents the flow of the `build-debug-android` workflow:
The following diagram represents the flow of the `lookup-cached-debug-build` workflow:

```mermaid
flowchart TD;
A["🔍 Lookup cached debug build (and skip all following steps if found)\nUsing <a href='/setup-ci/docs/aux-workflows/lookup-cached-debug-build'>lookup-cached-debug-build</a>"]-->B["💾 Maximize build space\nUsing <a href='https://github.com/AdityaGarg8/remove-unwanted-software'>AdityaGarg8/remove-unwanted-software</a>"]
B-->C["🌿 Setup Node"];
C-->D["☕ Setup JDK 17"]
D-->E["🐘 Setup Gradle 8.8"]
E-->F["📦 Install dependencies"];
F-->G["🛠️ Build [yarn build:debug:android]"]
G-->H["📡 Store built app in cache"]
flowchart LR;
A["🌿 Setup Node"]-->B["📦 Install dependencies"];
B-->C["🧬 Calculate fingerprint"];
C-->D["🐛 Lookup debug build in cache"];
```

#### build-debug-ios

The following diagram represents the flow of the `build-debug-ios` workflow:

```mermaid
flowchart TD;
A["🔍 Lookup cached debug build (and skip all following steps if found)\nUsing <a href='/setup-ci/docs/aux-workflows/lookup-cached-debug-build'>lookup-cached-debug-build</a>"]-->B["💾 Maximize build space\nUsing <a href='https://github.com/AdityaGarg8/remove-unwanted-software'>AdityaGarg8/remove-unwanted-software</a>"]
B-->C["🌿 Setup Node"];
C-->D["🔨 Use latest stable Xcode"]
D-->E["📦 Install dependencies"];
E-->F["🛠️ Build [yarn build:debug:ios]"]
F-->G["📡 Store built app in cache"]
```

## Known issues and limitations

- One of limitations of GitHub Actions is that cache is scoped and cannot be accessed between
arbitrary branches (see [#79](https://github.com/actions/cache/issues/79)). This means that
if a build with specific fingerprint is created on `feature-a` branch, then in `feature-b`
branch with the same fingerprint, the build is not visible and the app will be built again.
However, since the build is also created on main branch, once either `feature-a` or `feature-b`
is merged to main, the build will be cached and available for all existing and future branches in the repository.
18 changes: 9 additions & 9 deletions docs/docs-site/docs/introduction/command-line-options.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,12 @@ When using SCI by running `npx setup-ci`, you can provide additional option flag

The following are **feature flags** that can be used with `--preset` flag (they are ignored if `--preset` is not provided).

| Flag | Description |
| ---------- | ----------- |
| --lint | TODO |
| --jest | TODO |
| --ts | TODO |
| --prettier | TODO |
| --eas | TODO |
| --detox | TODO |
| --maestro | TODO |
| Flag | Description |
| ---------- | ------------------------------------------------------------------------- |
| --lint | Generate [ESLint workflow](/setup-ci/docs/workflows/eslint) |
| --jest | Generate [Jest workflow](/setup-ci/docs/workflows/jest) |
| --ts | Generate [Typescript check workflow](/setup-ci/docs/workflows/typescript) |
| --prettier | Generate [Prettier check workflow](/setup-ci/docs/workflows/prettier) |
| --eas | Generate [Detox workflow](/setup-ci/docs/workflows/detox) |
| --detox | Generate [Maestro workflow](/setup-ci/docs/workflows/maestro) |
| --maestro | Generate [EAS Preview workflow](/setup-ci/docs/workflows/eas) |
81 changes: 74 additions & 7 deletions docs/docs-site/docs/introduction/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,8 @@ Setup CI (SCI) is a tool built by [Software Mansion](https://swmansion.com/) mea

## Why use Setup CI?

:::danger
TODO
:::
Setting up CI/CD workflows can be a time-consuming and error-prone process. Additionaly, experience shows that you do it only once in a while and it's easy to forget how to do it properly.
SCI allows to automate it using best practices to cache as much as possible to reduce used time and resources, allowing you to focus on developing your app instead of configuring pipelines.

## How to use

Expand Down Expand Up @@ -55,7 +54,75 @@ You can find more information about available option flags in [Command line opti

## Example usage

:::danger
TODO (similar to example in monorepo section)
With explanation of generated yml files
:::
Let's say we have a React Native project called `my-rn-project` and we want to set up Prettier and Typescript checks to run on every Pull Request. We can use SCI to do it for us.

```bash
cd my-rn-project
npx setup-ci --preset --prettier --ts
```

After the command finishes, we obtain some information about what happened. For example, we can see a list of all files that SCI added or modified for us.

```bash showLineNumbers
▼ The following files have been added or modified:

my-rn-project
├── package.json (~)
├── yarn.lock (~)
├── .github/workflows
│ ├── prettier.yml (+)
│ └── typescript.yml (+)
├── .prettierrc (+)
├── .prettierignore (+)
└── .nvmrc (+)
```

We can also see a list of manual steps that we need to perform to finish the setup.

```
╭───────────────────────────────── What next? ──────────────────────────────────
► Couldn't retrieve your project's node version. Generated .nvmrc file with default
node version (v20.17.0). Please check if it matches your project and update if necessary.
╰───────────────────────────────────────────────────────────────────────────────
```

Let's break down this output to see what exactly happened:

- `package.json` and `yarn.lock` files were modified, because SCI installed some missing dependencies and added scripts to `package.json`
- `.github/workflows` directory was created with two files: `prettier.yml` and `typescript.yml` - these are the CI workflows that SCI generated for Prettier and Typescript checks
- `.prettierrc` and `.prettierignore` files were added - these are the default configuration files for Prettier which SCI added because no Prettier configuration was detected in the project
- `.nvmrc` file was added - this is because no file with node version was found. We can also see that in the "What next?" list, SCI
suggests verifying that the default node version in `.nvmrc` matches the project's requirements

This all looks great, we can also verify how the workflows actually look like. Let's inspect `.github/workflows/prettier.yml`.

```yaml title=".github/workflows/prettier.yml" showLineNumbers
name: Prettier check

on:
pull_request:

jobs:
prettier-check:
name: Prettier check
runs-on: ubuntu-latest
steps:
- name: 🏗 Setup repo
uses: actions/checkout@v4

- name: 🌿 Setup Node
uses: actions/setup-node@v4
with:
node-version-file: '.nvmrc'
cache: 'yarn'

- name: 📦 Install dependencies
run: yarn install --immutable

- name: ✨ Run Prettier check
run: yarn prettier:check
```
Seems to be a reasonable GitHub Actions workflow! For more explanation about SCI and specific workflows, check out the following sections!
2 changes: 1 addition & 1 deletion docs/docs-site/docs/introduction/node-version.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ where specific version of node is set. It should look more or less like this:
cache: "yarn"
```
For more information about `actions/setup-node`, check https://github.com/actions/setup-node.
For more information about check [actions/setup-node](https://github.com/actions/setup-node).
## Node version file
Expand Down
2 changes: 1 addition & 1 deletion docs/docs-site/docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ const config = {
position: 'right',
},
{
href: 'hhttps://github.com/software-mansion/setup-ci',
href: 'https://github.com/software-mansion/setup-ci',
position: 'right',
className: 'header-github',
'aria-label': 'GitHub repository',
Expand Down

0 comments on commit 1afe949

Please sign in to comment.