From 7a54c87fde71a771d706dcf68ac38c3b5ad62108 Mon Sep 17 00:00:00 2001 From: Luis Date: Mon, 30 Oct 2023 13:26:09 +0100 Subject: [PATCH] Added Getting Started to README --- .envrc | 2 + .gitea/workflows/ui_assets.yaml | 4 +- README.md | 98 +++++++++++++++++++++++++++++++-- pkgs/merge-after-ci/default.nix | 2 +- pkgs/ui/.vscode/settings.json | 5 ++ 5 files changed, 102 insertions(+), 9 deletions(-) create mode 100644 pkgs/ui/.vscode/settings.json diff --git a/.envrc b/.envrc index 503fb6b..59cec38 100644 --- a/.envrc +++ b/.envrc @@ -3,3 +3,5 @@ if ! has nix_direnv_version || ! nix_direnv_version 2.3.0; then fi use flake + + diff --git a/.gitea/workflows/ui_assets.yaml b/.gitea/workflows/ui_assets.yaml index bb6e807..f0475d0 100644 --- a/.gitea/workflows/ui_assets.yaml +++ b/.gitea/workflows/ui_assets.yaml @@ -15,7 +15,7 @@ jobs: id: changed-files uses: tj-actions/changed-files@v32 with: - fetch-depth: 2 + fetch-depth: 0 - name: Check if UI files are in the list of modified files run: | @@ -35,7 +35,7 @@ jobs: export PATH=$PATH:$DEPS # Setup git config - git config --global user.email "ui-asset-bot@clan.lol" + git config --global user.email "ui-asset-bot@gchq.icu" git config --global user.name "ui-asset-bot" ################################################ diff --git a/README.md b/README.md index e1f5ad0..0e3d994 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,95 @@ -# clan.lol core +# Website Template -This is the monorepo of the clan.lol project -In here are all the packages we use, all the nixosModules we use/expose, the CLI and tests for everything. +This repository is a template to build high quality websites as a team. +The frontend uses [React NextJS +](https://nextjs.org/) and the backend uses Python with the [Fastapi framework](https://fastapi.tiangolo.com/). To ensure API compatibility between frontend and backend an `openapi.json` file is generated from the Python backend code, which defines the REST API. This `openapi.json` file is then fed into [Orval](https://orval.dev/), which generates Typescript bindings for the Rest API. To ensure code correctness, we use [mypy](https://mypy-lang.org/) to ensure the Python code is correctly statically typed, and [pytest](https://docs.pytest.org/en/7.4.x/) for backend tests. A Continuos Integration (CI) Bot, verifies the code with previously mentioned Quality Assurance (QA) tools and blocks Pull requests if any errors arise. +For dependency management we use the [Nix package manager](https://nixos.org/) to ensure reproducibility. -## cLAN config tool +## Getting Started: Development Environment -- The quickstart guide can be found here: [here](/clan/clan-core/src/branch/main/docs/quickstart.md) -- Find the docs [here](/clan/clan-core/src/branch/main/docs/clan-config.md) +1. Install the Nix package manager by [downloading the nix installer](https://github.com/DeterminateSystems/nix-installer/releases) or executing this command: + +```bash +curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install +``` + +2. Install direnv by [downloading the direnv package](https://direnv.net/docs/installation.html) or executing this command: + +```bash +curl -sfL https://direnv.net/install.sh | bash +``` + +3. Clone the repository and cd into it +4. You should see an error message reading like this: + +```bash +direnv: error .envrc is blocked. Run `direnv allow` to approve its content +``` + +5. Execute `direnv allow` to allow automatically executing the shell script `.envrc` on entering the directory +6. Go to `pkgs/clan-cli` and execute + +```bash +direnv allow +``` + +Then wait for the backend to build +7. To start the backend server then execute: + +``` +clan webui --reload --no-open --log-level debug +``` + +The server will automatically restart if any Python file changes. +8. In a different shell go to `pkgs/ui` and execute + +```bash +direnv allow +``` + +Then wait for the frontend to build. +9. To start the frontend, execute: + +```bash +npm run dev +``` + +Visit the website by going to [http://localhost:3000](http://localhost:3000) + +## Getting started: Setup Git Workflow + +1. Register your Gitea account locally by executing + +```bash +tea login add +``` + +You will then see a prompt, please fill it out like outlined below: + +``` +? URL of Gitea instance: https://gitea.gchq.icu +? Name of new Login [gitea.gchq.icu]: gitea.gchq.icu:7171 +? Do you have an access token? No +? Username: MyUserName +? Password: ********** +? Set Optional settings: No +``` + +2. First add your changes to git: + 1. `git add ` your changes + 2. Execute `nix fmt` to lint your files + 3. `git commit -a -m "My descriptive commit message"` +3. To automatically open up a pull request, that gets merged if all tests pass execute: + +```bash +merge-after-ci +``` + +4. Go to https://gitea.gchq.icu to the project page, and look under "Pull Requests" if there are any issues with it. +5. If there are issues, fix them and redo step 2. Afterwards execute + +``` +git push origin HEAD:MyUserName-main +``` + +to directly push to your open pull request diff --git a/pkgs/merge-after-ci/default.nix b/pkgs/merge-after-ci/default.nix index 1dfc7d4..7adaf20 100644 --- a/pkgs/merge-after-ci/default.nix +++ b/pkgs/merge-after-ci/default.nix @@ -21,6 +21,6 @@ writeShellApplication { remoteName="''${1:-origin}" targetBranch="''${2:-main}" shift && shift - tea-create-pr "$remoteName" "$targetBranch" --assignees consulting-bot "$@" + tea-create-pr "$remoteName" "$targetBranch" --assignees merge-bot "$@" ''; } diff --git a/pkgs/ui/.vscode/settings.json b/pkgs/ui/.vscode/settings.json new file mode 100644 index 0000000..21a3b87 --- /dev/null +++ b/pkgs/ui/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "search.exclude": { + "**/.direnv": true + } +} \ No newline at end of file