feat(doc): #940 move sections

- Move several sections to new docs page - Other minor changes Signed-off-by: Daniel Salazar <podany270895@gmail.com>
fluidattacks · Mar 8, 2023 · 64e623d · 64e623d
1 parent 1ab06a4
commit 64e623d
Show file tree

Hide file tree

Showing 13 changed files with 250 additions and 5 deletions.
diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml
@@ -1,15 +1,32 @@
-site_name: Makes Documentation
+site_name: 🦄 Makes
 site_url: https://fluidattacks.github.io/makes/
 site_description: Documentation for Makes
 site_author: Fluid Attacks
 repo_url: https://github.com/fluidattacks/makes
 repo_name: Makes
 copyright: Copyright © 2023 Fluid Attacks, We hack your software. All rights reserved.
 
+nav:
+  - index.md
+  - configuring-ci-cd.md
+  - versioning.md
+  - architecture.md
+  - contributing.md
+  - governance.md
+  - Security:
+      - security/introduction.md
+      - security/assurance.md
+      - security/design-principles.md
+      - security/slsa.md
+      - security/threat-model.md
+
 strict: true
 docs_dir: src
 theme:
   name: material
+  features:
+    - content.code.copy
+    - navigation.instant
 markdown_extensions:
   - pymdownx.superfences:
       custom_fences:

diff --git a/docs/src/README.md b/docs/src/README.md
diff --git a/docs/src/architecture/README.md → docs/src/architecture.md b/docs/src/architecture/README.md → docs/src/architecture.md
diff --git a/docs/src/configuring-ci-cd.md b/docs/src/configuring-ci-cd.md
@@ -0,0 +1,131 @@
+# Configuring CI/CD
+
+A Makes container can be found
+in the [container registry](https://github.com/fluidattacks/makes/pkgs/container/makes).
+
+You can use it
+to run Makes on any CI/CD provider
+that supports containers.
+
+Below you will find examples
+for running makes
+on some of the most popular
+CI/CD providers.
+
+## Configuring on GitHub Actions
+
+[GitHub Actions](https://github.com/features/actions)
+is configured through
+[workflow files](https://docs.github.com/en/actions/reference/)
+located in a `.github/workflows` directory in the root of the project.
+
+The smallest possible workflow file
+looks like this:
+
+```yaml
+# .github/workflows/dev.yml
+name: Makes CI
+on: [push, pull_request]
+jobs:
+  helloWorld:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b
+      - uses: docker://ghcr.io/fluidattacks/makes:23.04
+        # You can use any name you like here
+        name: helloWorld
+        # You can pass secrets (if required) as environment variables like this:
+        env:
+          SECRET_NAME: ${{ secrets.SECRET_IN_YOUR_GITHUB }}
+        with:
+          args: m . /helloWorld 1 2 3
+
+  # Add more jobs here, you can copy paste jobs.helloWorld and modify the `args`
+```
+
+## Configuring on GitLab CI/CD
+
+[GitLab CI/CD](https://docs.gitlab.com/ee/ci/)
+is configured through a
+[.gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/) file
+located in the root of the project.
+
+The smallest possible .gitlab-ci.yml
+looks like this:
+
+```yaml
+# /path/to/my/project/.gitlab-ci.yml
+/helloWorld:
+  image: ghcr.io/fluidattacks/makes:23.04
+  script:
+    - m . /helloWorld 1 2 3
+# Add more jobs here, you can copy paste /helloWorld and modify the `script`
+```
+
+Secrets can be propagated to Makes
+through [GitLab Variables](https://docs.gitlab.com/ee/ci/variables/),
+which are passed automatically to the running container
+as environment variables.
+
+## Configuring on Travis CI
+
+[Travis CI](https://travis-ci.org/)
+is configured through a [.travis.yml](https://config.travis-ci.com/) file
+located in the root of the project.
+
+The smallest possible .travis.yml
+looks like this:
+
+```yaml
+# /path/to/my/project/.travis.yml
+os: linux
+language: nix
+nix: 2.3.12
+install: nix-env -if https://github.com/fluidattacks/makes/archive/23.04.tar.gz
+env:
+  global:
+    # Encrypted environment variable
+    secure: cipher-text-goes-here...
+    # Publicly visible environment variable
+    NAME: value
+jobs:
+  include:
+    - script: m . /helloWorld 1 2 3
+  # You can add more jobs like this:
+  # - script: m . /formatBash
+```
+
+Secrets can be propagated to Makes through
+[Travis Environment Variables](https://docs.travis-ci.com/user/environment-variables),
+which are passed automatically to the running container
+as environment variables.
+We highly recommend you to use encrypted environment variables.
+
+## Configuring the cache
+
+If your CI/CD will run on different machines
+then it's a good idea
+to setup a distributed cache system
+using [Cachix](https://cachix.org/).
+
+In order to do this:
+
+1. Create or sign-up to your Cachix account.
+2. Create a new cache with:
+   - Write access: `API token`.
+   - Read access: `Public` or `Private`.
+3. Configure `makes.nix` as explained in the following sections
+
+### Configuring trusted-users
+
+If you decided to go
+with a Multi-user installation
+when installing Nix,
+you will have to take additional steps
+in order to make the cache work.
+
+As the Multi-user installation
+does not trust your user by default,
+you will have to add yourself
+to the `trusted-users` in the
+[Nix Configuration File](https://www.mankier.com/5/nix.conf).
diff --git a/docs/src/contributing/README.md → docs/src/contributing.md b/docs/src/contributing/README.md → docs/src/contributing.md
diff --git a/docs/src/governance/README.md → docs/src/governance.md b/docs/src/governance/README.md → docs/src/governance.md
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -0,0 +1,49 @@
+# Getting started
+
+## Installation
+
+1. [Install Nix](https://nixos.org/download).
+   > **Note**
+   > We recommend getting the Single-user installation
+   > if you're new to Nix.
+2. Install Makes:
+
+   ```bash
+   $ nix-env -if https://github.com/fluidattacks/makes/archive/23.04.tar.gz
+   ```
+
+## Usage
+
+The Makes command has the following syntax:
+
+```bash
+$ m <repo> <job>
+```
+
+where:
+
+- `<repo>` is a GitHub, GitLab or local repository.
+- `<job>` is a Makes job
+  that exists within the referenced repository.
+  If no job is specified,
+  Makes displays all available jobs.
+
+You can try:
+
+- `$ m github:fluidattacks/makes@main`
+- `$ m github:fluidattacks/makes@main /helloWorld`
+- `$ m gitlab:fluidattacks/makes-example-2@main`
+- `$ m /path/to/local/repo`
+
+Makes is powered by [Nix](https://nixos.org).
+This means that it is able to run
+on any of the
+[Nix's supported platforms](https://nixos.org/manual/nix/unstable/installation/supported-platforms.html).
+
+We have **thoroughly** tested it in
+x86_64 hardware architectures
+running Linux and MacOS (darwin) machines.
+
+## Want to get your hands dirty?
+
+Jump right into our [hands-on example](https://github.com/fluidattacks/makes-example)!
diff --git a/docs/src/security/assurance/README.md → docs/src/security/assurance.md b/docs/src/security/assurance/README.md → docs/src/security/assurance.md
diff --git a/.../src/security/design-principles/README.md → docs/src/security/design-principles.md b/.../src/security/design-principles/README.md → docs/src/security/design-principles.md
diff --git a/docs/src/security/README.md → docs/src/security/introduction.md b/docs/src/security/README.md → docs/src/security/introduction.md
@@ -1,4 +1,4 @@
-# Security
+# Introduction
 
 This section evaluates Makes using various standards
 and tries to address the security of Makes as an ecosystem

diff --git a/docs/src/security/slsa/README.md → docs/src/security/slsa.md b/docs/src/security/slsa/README.md → docs/src/security/slsa.md
diff --git a/docs/src/security/threat-model/README.md → docs/src/security/threat-model.md b/docs/src/security/threat-model/README.md → docs/src/security/threat-model.md
diff --git a/docs/src/versioning.md b/docs/src/versioning.md
@@ -0,0 +1,51 @@
+# Versioning scheme
+
+We use [calendar versioning](https://calver.org/) for stable releases.
+
+Versioning is the same for both GitHub tags and Containers.
+
+You can find
+the full list of versions in the
+[GitHub releases page](https://github.com/fluidattacks/makes/releases).
+
+The Makes ecosystem has two components:
+the framework itself, and the CLI (a.k.a. `$ m`).
+
+## Stable releases
+
+Stable releases are the ones that **do not have** the `Pre-release` label.
+they are frozen.
+We don't touch them under any circumstances.
+
+## Unstable releases
+
+Unstable releases are the ones
+that **do have** the `Pre-release` label.
+These releases have the latest Makes features
+but can also come with breaking changes or bugs.
+
+## Versioning scheme for the framework
+
+You can ensure
+that your project is always evaluated
+with the same version of Makes
+by creating a `makes.lock.nix` in the root of your project,
+for instance:
+
+```nix
+# /path/to/my/project/makes.lock.nix
+{
+  makesSrc = builtins.fetchGit {
+    url = "https://github.com/fluidattacks/makes";
+    ref = "refs/tags/23.04";
+    rev = ""; # Add a commit here
+  };
+}
+```
+
+## Compatibility information
+
+For the whole ecosystem to work
+you need to use the **same version**
+of the framework and the CLI.
+For example: `23.04`.