Skip to content

Getting started

Jump to bottom
Marc-Molio edited this page Jun 15, 2023 · 3 revisions

Getting Started (as developer)

This guide will help you getting started as a contributor to the project (and thank you for that)!

We expect you already have a github user and have joined this project (otherwise, that would be step 0 ;)).

Software and tools

The first thing you need to do, is get the correct software and tools installed.

Windows

Linux

Setup local Python environment

pre-commit install

Git submodules (for Backend)

This repo contains git submodules. When cloning repos with submodules, one can add --recurse-submodules to the git clone command, to automatically initialize and update each submodule in the repo, i.e.:

git clone --recurse-submodules <repo-url>

If you already cloned the repo and forgot --recurse-submodules, you can cd to the cloned repo and obtain the same results by running:

git submodule update --init --recursive

After running either of these commands, you will have initialized, fetched and checked out any nested submodules. The following section contains descriptions on how to config your local git environment to work more smoothly with submodules.

Additional config to work smoothly with git submodules

All the git config <...> commands in this section can be run with either --local (which is the default) or --global prefixes depending on your preferences for your local git setup.

Get an overview of changes to submodule

When running git status, Git will also show you a short summary of changes to your submodules, if you run the following:

git config status.submodulesummary 1

Pulling submodule changes from remote (updating local submodules)

To update our local version of the submodules in this project with latest changes of all remote submodules, run the following:

git submodule update --remote Afterwards, you can commit and push the incoming submodule changes like any other git change - make sure to verify that your local changes function with the submodule changes that you just pulled.

If you're only interested in updating one of the submodules, you can simply pass the name of the relevant submodule, i.e. git submodule update --remote "libs/utils"

Pushing submodule changes

To ensure that your awesome local changes to any submodules are available to other developers, make sure you configure git to automatically try pushing submodule changes:

git config push.recurseSubmodules on-demand

This also ensures that if your local submodule changes fail to be pushed for some reason, the main project push will also fail.

Submodule aliases - to speed up your CLI workflow

As suggested in the git submodules guide, setting up git aliases can come in very handy. A good example of setting up a git alias for a command that you will find yourself running a lot is git config --local alias.subupdate "submodule update --init --recursive". By running this command you add a local ( could be global if you prefer) alias to your gitconfig, allowing you to run the submodule update command with git subupdate.

Backend Folder Structure

modules/  # Contains our modules
    documentation/  # Documentation module (git submodule)
    project/  # Project module (git submodule)
    router/  # API Gateway implemented with Apollo Router
pyproject.toml  # Config for Black and ISort
.pre-commit-config.yaml  # Config for Pre-Commit
skaffold.yaml  # Skaffold config for running all backends

Run and Test Backend

Setup local .env Copy the contents of .env.example to a local .env file. Populate the values and source .env before starting Skaffold To set the content of the .env file as env vars run export $(grep -v '^#' .env | xargs)

Copy GraphQL schemas

If it is your first time running Skaffold then you have to initialize the Graphql schemas for the Router.

mkdir -p modules/schemas/project
mkdir -p modules/schemas/documentation

cp modules/project/graphql/schema.graphql modules/router/schemas/project
cp modules/documentation/graphql/schema.graphql modules/router/schemas/documentation

Run

# Make sure Minikube is running
minikube start

# Set env var
export ARTIFACTS_TOKEN_BACKEND_PACKAGES=<YOUR_PAT>

# Start Skaffold
skaffold dev

Test

Running tests should be in each individual module. See README there.

Frontend

Copy the .env.example to .env and populate the values.

To start the dev server npm run dev

To run unit tests npm run test

To run interactive Cypress tests npm run e2e:open

NOTE: before running the e2e tests the following env vars need to be set:

CYPRESS_AAD_TENANT_ID=
CYPRESS_AAD_CLIENT_ID=
CYPRESS_AAD_APP_CLIENT_SECRET=
CYPRESS_TEST_USER_EMAIL=
CYPRESS_TEST_USER_PASSWORD=

To generate GraphQL hooks npm run codegen

Development Setup with other @lcacollect packages

You can use npm link to set up live reloading of the other @lcacollect packages.

  • Clone the package that you wish to enable live reload on.
  • In the terminal, go the root folder of the cloned repo and write npm link in the terminal
  • Go back to this repo's root folder and write npm link @lcacollect/{PACKAGE} to link the package.
  • When you make changes to the package, that you wish to see in this app, simply run npm run build in the package and the changes will available here.

Folder Structure and Naming (for Frontend)

cypress/ # Contains E2E tests
    e2e/ # The tests themselves
    fixtures/ # Mock data
    support/ # Helper functions
src/ # Contains the source code
    app/ # Contains the App component
    assets/ # Contains assets, such as images
    components/ # React components
        myComponent/ # Each component has its own folder
            index.ts # Export of what is public
            myComponent.tsx # The component
            myComponent.spec.tsx # Unit test file
    dataAccess/ # Apollo Client folder
        generated.ts # Autogenerated file from Apollo with React Hooks for data fetching
        schema.graphql # File for writing GraphQL queries
    pages/ # Page components
    routes/ # Routing for the app

Further Documentation

Further documentation for LCAcollect can be found here

License

Unless otherwise described, the code in this repository is licensed under the Apache-2.0 License. Please note that some modules, extensions or code herein might be otherwise licensed. This is indicated either in the root of the containing folder under a different license file, or in the respective file's header. If you have any questions, don't hesitate to get in touch with us via email.

Clone this wiki locally