Architecture

PermaplanT is an app to help plan, develop and document permaculture gardens either by oneself or in groups. To do so, the garden is represented by a map. Layer by layer, supplied by the app, the user feeds the map with relevant environmental information. From the internal database of over 10.000 plants the users design the planting as they wish. The app informs about known relations between the plants and about environmental restrictions. Visual indications help users to make decisions. The date or time frame can be chosen in a timeline. Nextcloud is used to connect users, groups and gardens.

The most important chapters to read are:

These markdown files document the architecture of PermaplanT according to arc42.

Goals

The overall goals of the app are to enable planning:

vital growth of delicious edible crops, while
providing a diverse and functioning ecosystem, and
creating outdoor living spaces for both animals & humans.

To achieve these goals the app provides, e.g.:

visual indications for permaculture:
1. what makes sense according to known and easily measurable natural constraints
2. is practical for the gardener
3. enhances diversity and supports the ecosystem
suggestions for:
- what is seasonal
- increasing diversity

Non-functional Goals

aesthetic UI that is fun to use
low barriers for collaboration
low memory consumption and good performance
privacy: data should remain within Verein

Main Features

users have any number of maps
maps have any number of layers (see below)
some layers can have alternatives and/or can be used offline
users work on alternatives of layers on the same map together
undo/redo for changes in the map
copy&paste of selection including succeeding crops across maps
zoom
internationalization: English, German
algorithms for polyculture, considerations of natural constraints and automatic suggestions
Nextcloud integrations (calendar entries, Deck tasks)
social network features (e.g. notification that someone entered your garden)
privacy: no tracking, analytics, external JavaScript, fonts, etc.

Layers

In all layers --- except for base --- past, current or future entities might be intermixed. While editing any layer other layers are (transparently) displayed or hidden.

Base¹ (import photo or site plan as base image, define borders, scale, orientation)
Terrain
Landscape¹ (height&sketch of permanent structures like walls, ponds, constructions, beds)
Labels (allows to put text labels, e.g. names for beds)
Trees (taxa, stem position&height&sketch&type of forest, trees, hedge, bushes etc.)
Wind (more or less windy places, wind orientation)
Shade (more/less sun exposure vs. shade)
Infrastructure (outlets, wifi spots, taps, water storage tanks, irrigation systems, ...)
Hydrology (surface water runoff, natural reservoirs, gullies, rills, ...)
Soil (pH Values of topsoil, subsoil)
Paths (ways, fences, stepping stones)
Habitats (taxa, areas for (wild)life, nesting aids, heaps of stones or leaves, perches)
Zones (of different visitation frequency)
Plants¹ (taxa, individual and fields of plants)
Warnings¹
Photos (sharing of photo with GPS coordinates and a Nextcloud chats per photo)
Fertilization
Watering
Todos (creates Deck cards in Nextcloud)
Drawing (for anything else)

¹ Essential (most used) layers: are more prominently shown than others.

Use Cases

For more details about each requirement, continue reading Use Cases (Chapter).

Constraints

Guidelines must be either followed or a rationale for breaking the guideline must be given in a comment nearby

UI

UI should be hard to use wrong.
User experience should only be disturbed when necessary.
UI must be consistent:
- Colors
- Use toolbars
- Reuse components (in storybook)
- Keybindings
- personified error messages
- etc.

Rationale: to support main goal

Data Consistency

Users always see the latest data.
The data from the backend is the single source of truth. I.e., in conflicting scenarios always the backend takes preference.
In offline scenarios either the backend gets locked or the frontend gets read-only.

Rationale: we prefer collaboration over offline use.

Backend

We use REST with JSON
API calls should be for interactive use and as such terminate within parts of a second, five seconds maximum, see Graceful Shutdown for more information.

Graceful Shutdown

Actix by default handles shutdowns (see here for reference).
As soon as the signal SIGTERM is issued to the backend no new connections will be accepted.

Still running connection will be finished or terminated after 5sec.
API requests should ideally take no longer than a few seconds, with a 5-second limit for logging and optimization purposes.
Implementing this limit improves convenience for both developers (termination of endless loops) and continuous integration (faster restart on hanging API calls), with minimal complexity in the code.

Context & Scope

Context

Users see PermaplanT as mere tool to replace books and their notes. PermplanT envisions designing maps:

collaboratively
for agricultural purposes
enabling fully documenting all plants:
- for garden tours
- for tracking harvesting
reminding about what you don't see:
- watering
- fertilization
with mulching
but no dig

Out of Scope

Later features that are out of scope for first version:

weather data (automatically add rain to watering layer, warnings on frost etc.)
hints&tips about pest control, fertilizer, care, etc.
automatic shadow and moisture calculation
3D modes (forest garden), contour lines etc.
time-lapse of historic garden development, simulate growth
positions and distances relate to the real world, for example, you can use GPS coordinates
GIS import/export

Input Parameters

Soil

Global value and local values in the Soil layer:

soil texture (German: orientiert an Bodenschwereklasse nach ÖNORM L 1050 auf Basis des österreichischen Texturdreiecks bzw. Bodenartendiagramms (ÖNORM L 1061) (Klassen))
pH base value for topsoil from 0-14 (German: Bodenreaktion, e.g. Kohl basisch, ph3 Heidelbeeren), dynamic value using one decimal digit after the comma:
- 1 very acid (pH 5.0 and below)
- 2 acid (pH 5.1 - 6.5)
- 3 neutral (pH 6.6 - 7.3)
- 4 alkaline (pH 7.4 - 7.8)
- 5 very alkaline (pH 7.9 and above)
pH base value for subsoil from 0-14
yield grade (German: Ages Gehaltsklasse (Nährstoffversorgung und Humusgehalt) ÖNORM L 1210, determined from NPK, eigentlich für Intensivkultur, Stark/Schwachzehrer) from:
- A sehr niedrig
- B niedrig
- C ausreichend
- D hoch
- E sehr hoch

Out of Scope

(Temperatursumme/Jahresmitteltemperatur) first version: use data from Ostösterreich
(Vegetationsperiode) first version: use data from Ostösterreich
(sun background: Sonnentage, Sonnenscheindauer h, from https://www.data.gv.at/katalog/dataset/1d9754ae-9e7b-4772-97c9-a030285d75bb) first version: use data from Ostösterreich
(soil depth, BM: Bodenmächtigkeit: Mächtigkeit des durchwurzelbaren Mineralbodens (cm)) first version: assume "sehr tiefgründig" > 100cm
(SkelG: Skelettgehalt: Anteil der Korngrößenfraktion > 2 mm (Grobanteil) am Mineralboden (%)) first version we assume geringer Grobanteil <= 10%
Available water capacity
Field capacity
Permanent wilting point
(Gesamtniederschlag - Verdunstung) first version: use data from Ostösterreich

Local (for each place in the Garden)

distances to plants/trees (German: Abstände zu Bäumen/Sträuchern)
wind
shadows
surface water, i.e., wet/dry places (German: Oberflächenwasser)
habitats
permaculture zones, see glossary
events: e.g. elements in the garden get added/removed accurate to the day

Out of Scope

soil amendments
mulching (Mulchen)
influences of street (German: Einflüsse durch Straßennähe, wie Salz und Staub)
automatic overshadowing (German: Baumkronenüberschattung)

Output Parameters

which seeds are needed (seedling plants excluded)
coordinates of plants to plant
warnings (violation of natural constraints etc.)

Out of Scope

weather alerts

Solution Strategy

PermaplanT has a classical frontend/backend architecture:

the frontend is structured according features
the backend has a 3-layer architecture with a database

Type Safety

We use specific types (prefer enum over int over string etc.) and share types whenever possible:

Diesel is used to share types between the database and backend code. We use type-safe queries (and not raw queries), whenever possible.
typeshare is used to share types between Rust, API and Typescript.

Validation

The frontend should validate data as early as possible, usually during input using React Hook Form.
For more complex validation logic, we use Zod in conjunction with React Hook Form Schema Validation. For example Zod should be used over default React Hook Form validation when there are inter-dependent form values that need to be validated together, such as validating that a start date is before an end date.
All constraints that go beyond the types, e.g. automated validation while extracting via serde, should be explicitly validated by the backend as well as the frontend. This is because some constraints could be bypassed by just validating in the frontend. For example, payment data or data associated with gamification achievements should be validated in the backend to ensure data consistency and prevent security vulnerabilities.

State

Both frontend and database contain the latest and complete state.
The backend is state-less, all state is in the database or in the auth token.
The frontends map editor has structured state per layer.

See also frontend state management for which libraries are being used.

API

The API is implemented in the backend. The backend is stateless (except of the database) and agnostic to language. The backend serves no other purpose as being used by the frontend, so:

it can be tailored to the needs of the frontend
the frontend ideally only needs to do a single API call to get what it needs

Concurrent Use

The user wants to see changes that other users are making on the map, therefore the data needs to be kept in sync. The data is kept in sync between the client and the server through API calls with axios and server-sent events (SSE). This means the backend is always up to date with the users actions and users can see what others are doing.

Data must be sent immediately and asynchronously to the backend after any user action (via API).
Calculations in the backend can always assume that database is up-to-date.
No timestamps are needed for data consistency.
There is no conflict handling in the frontend.
If a user loses the connection, the frontend must go into a read-only state.
We use uuid to identify frontend-created database entries, like elements on the map.

Actions

Actions are minimal, encapsulated state changes from elements on the layer of a map. Such actions are used to:

describe user actions in the frontend (undo/redo, see later)
describe transport of 1. to the backend (via PATCH API calls)
describe transport of 1. back to other frontends (via SSE)

SSE

For SSE, browsers first request an event-source via the endpoint /api/updates/maps. Then the backend sends all updates of a map to all users connected to the maps. To do so, all API calls in the backend must notify the broadcaster. This includes all changes of elements but also changes to layers, map metadata, chat etc. Any polling should be avoided.

The broadcaster lives in AppDataInner, which is available in request handler via dependency injection in the request context. So every controller related to map endpoints must must use AppDataInner. At the end of every request handler, you need to have a statement like:

app_data.broadcaster.broadcast(map_id, action)

Note that login data is implemented differently.

Undo & Redo

Undo/redo is client-specific so a user can only undo their own changes. The undo/redo functionality is implemented by means of an inverse (opposite) action. For this to work the actions have to exactly encompass the state they are mutating.

For example, a movement action should only have the new coordinates and the identifier for the entity it moves, as well as an identifier for the action itself (using UUIDs), as payload.

type MovementAction {
  type: 'MOVEMENT_ACTION';
  payload: {
    id: string;
    actionId: string;
    x: number;
    y: number;
  };
}

The same actions are also used for communication to the backend.
Undo/redo gets lost if other users concurrently move or edit elements. For inspiration you can read more at this liveblocks.io blog post.

Performance

per user action only a minimal number of API calls should be used (ideally one)
relations are only calculated to plants within bounding box

PostGIS

Coordinates of all elements are stored via PostGIS types to have uniform access and to allow retrieving elements of segments of the map.

Low Memory Consumption

As the planning tools are also used for longer sessions, e.g. a whole working day, it is essential to keep the memory usage at acceptable levels:

state is strongly structured for performance reasons, every layer writes in its own parts
we only use essential layers at startup, see lazy loading
we do offloading of layers that are not used for some time, see offloading

To keep the backend with low memory consumption we try to avoid duplicating data from the database to memory other than when sending it to the client.

Layers

Layers are kept independent, they have their own:

state hierarchy
API calls to the backend

I.e. each layer is responsible to handle:

the time functionality (which elements are loaded and which are shown)
add, edit, move, remove and delete functionality
offload data

The implementation, however, should be shared.

Offline Changes

The user should also be able to access some features of the application while being offline and later synchronize her changes to the server. If a user requests to work offline, the layers will be locked for that user in the backend. While the lock is active, other users see these layers read-only.

Upon coming back online the changes made are synchronized and the lock is released.

Identity and Access Management

Only the landing page can be seen without registration. We use Keycloak for Identity and Access Management with 3 roles:

default-roles-permaplant (only public maps can be visited)
member (can do everything but administration tasks)
admin (possibility to change data from other users, as needed for onboarding or offboarding)

Privacy

In general all data must stay within the organisation (Verein). Members see other members' data only if they allowed it. Data which makes a person identifiable should be in Keycloak. The only exceptions are:

bank account and billing address, which gets completely removed from the server (for security reasons)
public maps are visible to non-members but most meta-data won't be shown and the location gets obfuscated

Coordinate System

The backend uses the same coordinate system as the frontend.

(0,0) is in the top left corner.
The x-value increases when going to the right and the y-value increases when going down.

The scale is set to be in cm, so increasing x by 1 would mean going to the right by 1cm.

The granularity of the heatmap is set to 10cm via the constant GRANULARITY in the backend.
This means that the heatmap is generated by dividing the maps geometry into 10x10cm squares for each of which a score is computed.

Building Block View

Backend Structure

config/: Contains the servers configuration.
controller/: Contains all endpoints of the application.
db/: Contains utility functions for the database.
model/: Contains the data PermaplanT is acting upon and their implementation.
service/: Contains business logic and maps between entities and DTOs.
test/: Contains integration tests.

graph LR;
    config -->|Configures routes<br>Uses endpoints for OpenAPI doc| controller
    config -->|Uses DTOs for OpenAPI doc| model
    controller -->|Calls functions| service
    controller -->|Uses DTOs| model
    controller -->|Uses data pool| db
    db -->|Uses `Page` struct| model
    model -->|Uses helper functions| db
    service -->|Calls database| model
    service -->|Uses DTOs and Entities| db

Controller

The controller layer contains all endpoints of the application.
The actual routes are defined here while the controller layer only contains the actual implementation of the endpoints.

When an endpoint gets called Actix clones an internally stored pool of connections to the database and passes it to the endpoint to be used.
We then 'forward' the pool to the service layer where a connection is retrieved from the pool.
The persistence layer then uses that connection to make calls to the database.

The endpoints are automatically documented using utoipa which can generate OpenAPI documentation from code.

Service

The service layer is responsible for handling our business logic as well as mapping entities and DTOs.

Model

The model/ folder contains the data PermaplanT is acting upon.
Entities are shared with the database using the ORM diesel.
DTOs are shared with the frontend using typeshare.

The files entity.rs and dto.rs contain the actual structs. That way you have a quick overview of what the data looks like without having to navigate multiple files.
The actual implementation of the structs is in separate files to reduce the line length of the files.

Frontend Structure

__mocks__/: Contains mocked modules for tests.
assets/: Contains small asset files like SVGs.
components/: Contains components that are shared across features.
config/: Contains initialization code for the environment and libraries.
features/: Contains the distinct features of the application.
generated/: Contains generated code.
- docs/: Automatically generated documentation.
- api_types/: The types generated via typeshare from the backend API.
hooks/: Contains hooks that are shared across features.
routes/: Contains the routes of the application.
styles/: Contains the global and other style sheets, e.g. to customize a component from a third party library like react-leaflet.
utils/: Contains additional utility functions, that are shared across features or components and are not hooks.

flowchart LR
  routes --> |Renders route features| features
  features -->|Uses types for API calls| generated/api_types
  features -->|Uses shared components| components
  features -->|Calls functions| config
  features -->|Uses hooks| hooks
  features -->|Calls functions| utils
  features -->|Uses asset files| assets
  features -->|Uses some miscellaneous styles| styles
  features ---->|Uses another feature's public API| i
    subgraph f[example feature]
      direction TB
      i[index]
      e[fa:fa-folder example feature structure] --> |Components scoped to a specific feature| c[components]
      e -->|API request declarations and API hooks related to a specific feature| a[API]
      e -->|Route components for a specific feature's pages| r[routes]
      e -->|State stores for a specific feature| s[stores]
    end

__mocks__ is not used during runtime

`mocks`

This folder has a special name to be recognized by our test runner vitest. More details on how mocking with vitest works can be found in the documentation.

`assets`

This folder should contain only small asset files like SVGs, so that our bundle size stays small. Larger files should be hosted on Nextcloud.

`generated/api_types`

This folder contains API types that are generated by typeshare. They can be regenerated by running the command npm run generate-api-types.

`components`

All components that reside inside here need to be documented in storybook.

The minimum requirements for documentation are:

If the component can be in different states (e.g. a visual variant, or an open/closed state), each state should be described by a story.
Every property that can be passed to the component needs to be documented.

`features`

Most of the application's code lives here. Every folder created here represents a given feature and contains its domain specific code. For example, if a feature interacts with the backend via network requests, it would have a sub module api that encapsulates this.

Features are allowed to import another feature's public API which is exported from its index.ts file. Features are also allowed to import all other previously mentioned modules if needed.

Each feature can have its own separate store to manage its state. This allows for modular and independent state management across different features.

Folder Structure for each Feature

api/: Contains API calls to the backend
components/: Contains components that are related to the feature.
hooks/: Contains hooks that are related to the feature.
routes/: Contains the routes of the feature.
utils/: Contains additional utility functions, that are related to the feature.
store/: Contains stores that manage state of the feature.

The `map_planning` feature

Store

The MapStore is related to the map planning feature and contains all layer-related state and logic. The main map store is composed of two sub-stores:

TrackedMapStore: stores the state of the map that is tracked by the history. This state is used to undo/redo actions.
UntrackedMapStore: stores the state of the map that is not tracked by the history (e.g., the selected layer and the layer opacities).

Components like the timeline or the transformer use separate independent stores. This separation allows the components or sub-features to manage its specific state that is not directly related to the map or layer management.

Additional Structure

layers/: Contains components and utilities that are related to layers. Each layer type has its own folder.

Subfeature Structure

If there are subfeatures such as a timeline or transformer component, corresponding subfolders named after the subfeature are created within directories like store or components to encapsulate their specific implementations.

Layer states

For each layer there is a TrackedLayerState and an UntrackedLayerState. If the layer introduces new properties the new types (e.g. TrackedPlantLayerState and UntrackedPlantLayerState) should be extended from these. The same applies for the corresponding ObjectState types.

add new types

/**
 * The state of an image object.
 */
export type ImageObjectState = ObjectState & {
  imageUri: string;
};

/**
 * The state of a map's photo layer.
 */
export type TrackedPhotoLayerState = {
  index: LayerName;
  /**
   * The state of the objects on the layer.
   */
  objects: ImageObjectState[];
};

modify layer type

/**
 * The state of the layers of the map.
 */
export type TrackedLayers = {
  [key in Exclude<LayerName, "Photo">]: TrackedLayerState;
} & {
  Photo: TrackedPhotoLayerState;
};

the above construct may eventually be refactored into the below as more specific types get added to the layer state.

export type TrackedLayers = {
  Base: TrackedBaseLayerState;
} & {
  Plant: TrackedPlantLayerState;
} & {
  Photo: TrackedPhotoLayerState;
} & {
  ...
}

Runtime View

Plantings

sequenceDiagram
    actor User
    User->>+Frontend: search for plant
    Frontend->>+Backend: search
    Backend->>-Frontend: list of plants
    User->>Frontend: selects plant
    Frontend->>+Backend: placements
    Backend->>-Frontend: list plant_ID of relations
    Backend->>-Frontend: heatmap
    User->>Frontend: place plant
    Frontend->>Backend: place plant

search via GET on /api/plants
placements via GET on /api/maps/{map_id}/layers/plants/placements
place plant via POST on /api/maps/{map_id}/layers/plants/plantings (plant_ID, pos, date)

Onboarding

sequenceDiagram
    actor User

    User->>Permaplant: visit landing page

    User->>Keycloak: self-registration
    activate Keycloak


    User->>Permaplant: visit public maps
    activate Permaplant

    Permaplant->>Nextcloud: use images etc.
    activate Nextcloud
    actor Admin

    User->>Permaplant: membership application
    Permaplant->>Admin: notification

    alt accept
        Admin->>Keycloak: change role to member and ask for email verification
    else accept
        Admin->>Keycloak: ask for new membership application
    end

    activate Keycloak
    Admin->>Permaplant: remove sensitive data
    Admin->>Nextcloud: change quota
    Admin->>User: notification via email
    deactivate Keycloak
    deactivate Keycloak
    deactivate Permaplant
    deactivate Nextcloud

Season

Example of a typical sequence in one season:

sequenceDiagram
    actor User
    User->>+App: input of available seeds
    User->>App: import base map
    User->>App: planning of landscape
    User->>App: planning of plants
    App->>-User: list of needed seeds
    World->>User: get missing seeds
    User->>World: raise plants indoor (vorziehen)
    User->>App: set batch as raised

    World->>User: plants ready, weather ok
    loop
        App->>User: batch (of plants) should be planted
        User->>World: plant batch in garden
        activate World
        User->>+App: set batch as planted


    end

    World->>User: harvest and remove plants
    deactivate World
    User->>App: set plants as harvested or removed
    World->>User: seeds for next year

Deployment

C4Context
    Person(person, "Non-Member", "Not yet one of PermaplanT's members.")
    Person(member, "Member", "Any of PermaplanT's members.")

    Boundary(browser, "Browser") {
        System(Frontend, "Frontend", "Allows to design permaculture maps.")
    }

    Boundary(server, "Server") {
        System(Backend, "Backend", "Implements PermaplanT's specific functionality.")

        System(Keycloak, "Keycloak", "Handles auth for Frontend, Backend and Nextcloud")

        System(Nextcloud, "Nextcloud", "Stores all files and allows collaboration.")

        SystemDb(Database, "Database", "PostgreSQL with PostGIS extensions.")
        System_Ext(Email, "Email", "The email system.")
    }


    BiRel(person, Frontend, "Sees landing page and public maps")

    BiRel(member, Frontend, "Uses with full functionality")

    BiRel(Frontend, Nextcloud, "Nextcloud REST API", "HTTPS")

    BiRel(Frontend, Backend, "PermaplanT REST API", "HTTPS")

    BiRel(Frontend, Keycloak, "Tokens", "HTTPS")

    Rel(Backend, Email, "")
    Rel(Nextcloud, Email, "")
    Rel(Keycloak, Email, "")

    BiRel(Database, Backend, "SQL")

    UpdateElementStyle(person, $fontColor="black", $bgColor="grey", $borderColor="red")
    UpdateRelStyle(person, Frontend, $offsetX="0", $offsetY="-60")

    UpdateRelStyle(member, Frontend, $textColor="b", $lineColor="blue", $offsetX="50", $offsetY="-20")

    UpdateRelStyle(Frontend, Backend, $textColor="blue", $lineColor="blue")
    UpdateRelStyle(Frontend, Keycloak, $textColor="blue", $lineColor="blue", $offsetX="-10")
    UpdateRelStyle(Frontend, Nextcloud, $textColor="blue", $lineColor="blue", $offsetX="-50")

    UpdateLayoutConfig($c4ShapeInRow="4", $c4BoundaryInRow="1")

Crosscutting Concepts

We handle crosscutting concepts in the Chapter Guidelines.

A few concepts we don't need/avoid/keep very simple are listed here:

persistency: only via database
transaction handling: shouldn't be only within endpoints

Architecture Decisions

We handle architecture decisions in its own Chapter Decisions.

Quality

operable

Migrations correctly migrate from previous version to the current one, without losing data etc. (within dev migrations can be modified or squashed).
Frontend+backend are (re)-deployed together, so there cannot be version mismatches.
Only a minimal set of configuration options and everything is configurable only via .env.
Everything builds and runs on Linux and the CI.

usability

Compliance with UI style-guide.
Easily understandable acceptance test cases.
Usability tests with own case studies and gardeners.
(Future) Usable despite color blindness.
(Future) Usable with tablet gloves.

efficient

At least 3000 users should be able to use the backend simultaneously.
Startup time of backend should be less than one second.
Near instant search results.
Good carbon emission efficiency.

secure

Avoid common vulnerabilities
Use reliable software for security concerns
Everything encrypted (https)
Only encrypted or local storage
Only authenticated users can access non-public data

flexible

One of our least important goals. Users or programmers do not need simple ways to extend PermaplanT or to change features. The only quality requirement we have are:

usage in different browsers, including tablets
localized to German and English

Backend Tests

Tests are split into unit and integration tests (see here for reference).

Integration tests can be found here.
Unit tests can be found in the modules they are supposed to test.

Code documentation

The code documentation of the backend can be built using cargo doc --open.

You can find a more detailed explanation of which modules do what there.

API documentation

The API documentation can be viewed by running the backend with cargo run and then navigating to http://localhost:8080/doc/api/swagger/ui/.
It is automatically built using utoipa.

Frontend Code Documentation

The code in the frontend is documented by two different mechanisms. On the one hand components are documented via storybook, on the other hand the public API of a feature, shared hook or utility, etc. should be documented by doc comments. We use TypeDoc to extract the documentation from code comments. More details about supported tags and syntax can be found in the TypeDoc documentation.

The code documentation of the frontend can be generated via the command npm run doc. Under the hood, this command executes TypeDoc that generates .mdx files to be viewed in storybook.

Afterwards it can be opened in storybook via the command npm run storybook.

More details about documentation can be found in the contribution docs

Risks and Technical Debt

Implementation Risks

implementation cannot be understood by future programmers
Mitigation: inline comments, assertions, documentation and test cases
misunderstandings about biology or plant relationships
Mitigation: have experts Yvonne and Pavlo included in our team.

Domain Risks

table design (SQL) not suitable for our domain
Mitigation: create ER diagram, documentation about hierarchy

Technical Risks

hardware risks
Mitigation: Having a second server.

Business Risks

unclear communication what PermaplanT is about
Mitigation: Do releases and advertise them, landing page.
too small group of users
Mitigation: it can be used at least for ourselves and by friends

Legal Risks

Glossary

Basics

PermaplanT:
The planning app implemented in this repository.
map:
The main planning utility for PermaplanT, which contains elements in several layers.
elements (of a map in a layer):
Can be drawn or added to the map via drag and drop. They have attributes.
garden:
The physical place which is represented by the map. Can also be balcony or similar.
event:
A day relevant to a user, which occurs on a map, e.g. when elements in the map get added/removed (accuracy: one day) or when a user declares a map ready for review etc.
deletion/creation vs. removal/adding of elements:
- deletion/creation (German: löschen/erzeugen): The plant never existed. Such elements actually get deleted from the database and can only be restored within the session using undo. I.e. there are often columns named created_date but there usually is not a deletion date (with exception of maps which do not immediately get deleted).
- removal/adding (German: entfernen/hinzufügen): Removal of elements assume that the element actually was on the map (physically) during some time (between adding and removing). The database must keep removed elements, they never can be deleted.

Biology

taxonomy:
A scientific classification of plants into a hierarchy. The hierarchy we use is described here. As first introduction read:
- permakultur konkret
- wikipedia
- Garten Treffpunkt
rank:
Rank is a level within taxonomy. Plants within one taxonomic rank share traits with each other. The levels relevant for PermaplanT are from highest to lowest:
- Family
- Genus
- Species
- Variety
- Cultivar
below:
We say a plant or rank B is below another rank A if it is at least one rank lower than A.
belong:
We say a plant B is belongs to rank A if it is exactly rank A (and not below).
concrete plant:
Is in an actually existing species, variety and cultivar.
abstract plant:
Representants of ranks, which are not actually existing plants.
family:
A taxonomic rank that consists of multiple genera.
genus:
A taxonomic rank which is part of a family. Consists of multiple species.
species (German: Art):
A taxonomic rank which is part of a genus. Can have multiple varieties or cultivars.
variety (German: Varietät):
Has the main characteristics of its species but differs in heritable characteristics. Can have multiple cultivars.
cultivar (abbreviated from cultivated variety, German: Sorte):
Has the main characteristics of its species or variety but differs in minor heritable characteristics. These characteristics were cultivated on purpose.
hybrid:
Hybrids are otherwise not relevant for PermaplanT's functionality.
attributes of plants (traits in scientific literature):
A characteristic of a variety, species, genus, subfamily or family. E.g. height, width, color, etc. Attributes can be defined on different levels of the hierarchy. E.g. a variety can have a different height than the species it belongs to.
polyculture (aka companion planting, German: Mischkultur):
Mutually beneficial way of growing plants together.
Relation:
- Spatial: Plants are in a non-neutral relation if they either positively (companion) or negatively (antagonist) influence each other's health and growth.
- Temporal: Plants are in a non-neutral relation if crop rotation is positive or negative on the later plant's health and growth.
companion (to plant according polyculture):
Plants that should be planted together.
antagonist (to plant according polyculture):
Plants that should be avoided next to each other.
plant database (German: Pflanzen-Datenbank):
PermaplanT's large collection of plant entries with comprehensive data, indexed with a unique name.
inventory (German: Inventar):
A personal collection of plants, e.g., seeds. Every entry of the inventory links to a plant in the plant database. Furthermore, they have an additional name and are more precisely describing a plant than the plant database could do. Only in the inventory you can have plants which are not in the plant database, e.g., of special, new or unknown varieties.
seedproof (German: Samenfest):
From the seeds of a fruit you get again similar fruits.
raising (German: Anzucht, vorziehen)
(German: Vorkulturen)
(German: Sortenrein, ohne/wenig Vermischung anderer Sorten, wenig/keine Fremdbestäubung)
zone (in permaculture, German: Permakultur Zonen):
Is an area which has the same frequency of human visitors. The areas are numbered from:
- 00: (represented numerically as -1)
- 0: physical body of permaculturist
- 1: extremely frequently visited
- 2: frequently visited
- 3: less frequently visited
- 4: rarely visited
- 5: usually not visited
- 6: never visited/protection zone

UI

Layer:
Layers allow to group elements of the same kind and set all of them visible or transparent. (implemented as Konva group)
Right top toolbar:
Allows to enable or hide layers.
Right bottom toolbar:
Contextual toolbar for the enabled layer.
Left top toolbar:
Buttons that have potentially global effects for the map or the functionality on the next click.
Left bottom toolbar:
Contextual toolbar for the enabled element.
Status panel:
Indicates what action a mouse click would have. Is not shown if mouse clicks would select elements.
Navigation Bar (NavBar):
The top bar for login etc.
Timeline:
The bottom bar to set the current date.

Layers

enable (a layer):
Changes the canvas in a way that elements in the enabled layer are the ones to be edited, selected and added. When working together on a map, every user can enable the layer of their choice.
visibility and opacity (of a layer):
The elements in a layer are (not) shown or with a user-selected transparency.
alternative (of a layer):
An alternative (of a layer) is a named clone of a layer. It is possible to select one alternative of a layer. Each alternative can be edited independently.
select (a layer):
To choose one alternative of one layer. E.g. if there are several plants layers, a user can select only one of these alternatives at once. When working together on a map, every user can select their own layers.
offline availability:
Means that layers can be edited also offline, data gets synced when device is online again.

Technical

usability:
The extent to which a system, product or service can be used by specified users to achieve specified goals with effectiveness, efficiency and satisfaction in a specified context of use.
user interface (UI):
The set of all the components of an interactive system that provide information and controls for the user to accomplish specific tasks with the interactive system.
user experience (UX):
Combination of user's perceptions and responses that result from the use and/or anticipated use of a system, product or service.
offline:
Means the ability to use a feature without Internet connection, i.e., without calling REST APIs.
canvas:
The main and middle part of the screen which provides the planning/drawing functionality.
canvas context:
- canvas node elements i.e. HTML representation of rectangle, circle, etc. on the canvas
map context:
- layers and their attributes e.g. relation layer and its visibility
reversible deletion vs undo-redo functionality:
- reversible deletion: a database entity i.e. a whole map and plant is deleted and can be restored within a certain time
- undo-redo functionality: a user can undo and redo changes in the map, but the history is local to the frontend and not stored in the database
lazy loading:
- Lazy loading refers to the process of loading data on-demand, rather than loading everything upfront during the initial load of the app.
offloading of the frontend state:
- the process of cleaning up the frontend state by deleting data that has already been synchronized with the backend and is no longer needed. This can help to reduce the amount of unnecessary data in the frontend, which can improve the performance and efficiency of the application.
first contentful paint (FCP):
- the time it takes for the browser to render the first bit of content on the page.
time to interactive (TTI):
- the time it takes for the page to become fully interactive.
Document Object Model (DOM):
- the data representation of the objects that comprise the structure and content of a document on the web.
endpoints:
- The API endpoints that can be called in the backend.
  Their documentation can be viewed using swagger-ui (see here for reference).
entity:
- an object or concept of interest (map, user, plant, planting, etc.)
- contains all necessary attributes to describe its properties
- represented as table in the database
- each database row is a specific instance of the entity
keybinding:
- The association of a specific action or function with a particular key or key combination.
keyhandling:
- A Broader concept of how the software manages and responds to keyboard input. It includes not only the assignment of actions to keys (keybinding) but also the handling of key events, such as detecting key presses, key releases, and processing them accordingly.

Testing

unit test:
Used to test parts of our code in isolation.
See test doc for further information.
Example: Test an individual function for specific behavior.
integration test:
Used to test if different parts of the code work together correctly.
See test doc for further information.
Example: Make an HTTP request to the backend and let it run through controller, service and persistence layer requiring a running database.
end to end test (e2e test):
Used to test the whole application from end to end.
Example: Simulate a user clicking a button (e.g. with Selenium) resulting in an HTTP request to the backend. Wait for the response and validate the resulting change in the frontend.
acceptance tests:
Black box system tests of a user story. Usually performed as regressions tests prior to a release. They are performed by engineers during the development phase.
system tests:
Tests the whole system towards the requirements definition and specification documents. This can involve functional and non-functional tests (performance, security, etc.). They are super set of end-to-end tests which can be done manually and/or automatically.
user acceptance tests:
Black box system tests towards customer requirements. Usually (subset of) system level tests conducted by the customer/user/domain expert. These tests makes sure that the solution provided by the system is accepted by the user. Similar to "Beta testing".

Authors

This is a list of people that contribute to PermaplanT, including their responsibilities, skills, etc.

Markus Raab

email: markus@permaplant.net
GitLab: @markus.raab
devel/test on: Debian stable
main responsibility: lead
focus groups: all

Yvonne Markl

email: yvonne@permaplant.net
GitLab: @EXT_26840233, @EXT_26873109
main responsibility: Biology
focus groups: frontend, UX

Aydan

devel/test on: Debian Oldstable/Stable
main responsibility: Releases and CI/CD

Paul

main responsibility: Offline Database Integration
focus group: DB, frontend
special skills: React, TypeScript, Tailwind CSS
positioning: full-stack

Christoph Schreiner

GitLab: @e01129489
main responsibilities: DB optimizations, Backend, E2E Tests
special skills: SQL, Python
focus group: Backend, PostGIS, E2E
positioning: Backend

Jannis Adamek

Gitlab: @e11809490
main responsibilities: layers
positioning: backend

Lukas L

Gitlab: @e12122567
main responsibilities: hydrology, crop rotation
positioning: frontend

Andrei D

Gitlab: @e01631854
main responsibilities: scrum processes, state management, copy+paste
positioning: frontend, scrum

Lukas H

GitLab: @e11776180
main responsibility: infrastructure
skills: CI, Jenkins, Ansible, Infrastructure

Filip

Gitlab: @e12024750
main responsibilities: CI, Infrastructure
skills: CI, Jenkins, Ansible, Infrastructure

Stefanie F

Gitlab: @e01609368
main responsibilities:
positioning: frontend

Previous Authors

Gabriel

main responsibility: Backend
special skills: Rust, Docker, OAuth2
positioning: backend

Nursultan

main responsibility: scraper, plant DB
focus group: DB
special skills: frontend tests
research: optimizations
positioning: full-stack

Benjamin

main responsibility: Polyculture
focus group: polyculture, PostGIS
special skills: BOKU
positioning: backend

Christoph

main responsibility: Database & Security Analysis
focus group: Security Analysis
positioning: DB

Christoph N

main responsibility: Usability Improvements
focus groups: UX, frontend
positioning: frontend

Samuel

main responsibilities: Nextcloud Integration, Frontend Architecture
focus groups: UX
special skills: SQL, Tailwind CSS, TypeScript
positioning: frontend

Giancarlo

main responsibility: Drawing Part of Frontend (Canvas)
focus group: UX
positioning: full-stack

Ramzan

main responsibility: PostGIS
focus group: DB, PostGIS
positioning: DB

Thorben

main responsibility: Gamification
worked on: DB, gamification, frontend, colors
focus group: DB, frontend, gamification
special skills: Jenkins
positioning: frontend, DB

Moritz

GitLab: @e52005233
main responsibilities: DB
special skills: SQL, TypeScript
focus groups: DB, Frontend
positioning: full-stack
worked on: seeds use case, base layer use case, db, frontend, backend

Daniel S

Gitlab: @e01627761
main responsibilities: timeline, drawing layer
positioning: frontend

PermaplanT Backend

Requirements

Rust (Installation guide)
PostgreSQL version 13 with PostGIS 3.1.1
libpq-dev
libssl-dev
pkg-config

Additional Documentation

Instead of setting up psql server on your local machine, you could use a 'postgis' Docker container.

Details about the setup can be found here

Details about the API documentation can be found here.

To view code documentation run the following in the backend/ folder:

cargo doc --open

Setup

All steps mentioned here have to be executed in the backend/ folder.

Setup

Rename .env.sample to .env and enter the data according to your setup.

DATABASE_URL is the Connection URI to your PostgreSQL database
BIND_ADDRESS_HOST defines the host on which the server will run on
BIND_ADDRESS_PORT defines the port on which the server will run on
AUTH_DISCOVERY_URI the .well-known endpoint of the auth server (see RFC 8414 for more detail)
AUTH_CLIENT_ID the client id the frontend should use to log in
RUST_LOG used to set the logging config for env_logger

To install an extension, a user needs to be a 'superuser',

The user 'permaplant' doesn't have the required permissions to create the 'postgis' extension.

Set it up using the postgres user.

Ensure that you grant the necessary permissions for the user to use Postgres.

One way to do this, is by using the following command:

sudo -u postgres psql
CREATE USER permaplant WITH CREATEDB PASSWORD 'permaplant';
ALTER USER permaplant WITH SUPERUSER;

Install

To install dependencies.

make install

migration

To update the database.

make migration

build

make build

Start Keycloak

You can do one of the following two steps, the first one being the simpler one, but with less configuration options.

To use the preconfigured Keycloak instance simply copy the newest version of .env.sample to .env
To use the local Keycloak variant follow the steps in Keycloak Setup
You then also have to change following two env variables in .env
- AUTH_DISCOVERY_URI=http://localhost:8081/realms/PermaplanT/.well-known/openid-configuration
- AUTH_CLIENT_ID=PermaplanT

To start the server

make run

Test server using Swagger

Go to http://localhost:8080/doc/api/swagger/ui/.
Now follow the steps described in the API documentation page.

You can find other ways to make requests by following How to obtain access tokens.

How to obtain access tokens?

In this guide it will be explained how to obtain access tokens and make requests to the backend while developing.

Be careful not to leak your username/password or access_token during the following steps.

Using Postman

Open Postman.
Create a new request.
- Enter the URL http://localhost:8080/api/config and execute the request.
  This should now execute without errors.
- Enter http://localhost:8080/api/seeds.
  You should get a status code 401 Unauthorized.
Click the Authorization tab and select OAuth 2.0.
- Chose Grant Type Authorization Code.
- Set Callback URL to http://localhost:5173/.
- Set Auth URL to https://auth.permaplant.net/realms/PermaplanT/protocol/openid-connect/auth.
- Set Access Token URL to https://auth.permaplant.net/realms/PermaplanT/protocol/openid-connect/token.
- Set Client ID to localhost.
- Click Get New Access Token at the bottom.
  - Postman should now open a browser window.
  - Enter your credentials.
  - There should now be a window displaying Authentication complete.
  - Once it closes click Use Token.
You should now be able to execute the request to http://localhost:8080/api/seeds in Postman.

A more in depth explanation about Postman and OAuth 2.0 can be found in the Postman documentation.

Using Curl

The following request should work without problems:
curl 'http://localhost:8080/api/config' -f

The following request should fail:
curl 'http://localhost:8080/api/seeds' -f

We need to obtain an access token before we are able to make requests to secured endpoints via curl.
We can do this using the Resource Owner Password Flow:

curl --request POST \
  --url 'https://auth.permaplant.net/realms/PermaplanT/protocol/openid-connect/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=password \
  --data 'username={username}' \
  --data 'password={password}' \
  --data 'client_id=localhost'

The response should be JSON containing a key access_token.
Copy the access token.
You can now make the request like the following:
curl 'http://localhost:8080/api/seeds' -H "authorization: Bearer {access_token}"

Note that the token is only valid for 5 minutes after which you have to refresh it with the same curl command again.

Other ways

You can find other ways of obtaining tokens using the Resource Owner Password Flow here.

API documentation

There are multiple variants of the API documentation:

Production: https://www.permaplant.net/doc/api/swagger/ui/.
MR: https://mr.permaplant.net/doc/api/swagger/ui/.
Dev: https://dev.permaplant.net/doc/api/swagger/ui/.
Local: http://localhost:8080/doc/api/swagger/ui/ (you have to have the backend running locally for this).

Executing requests

You can test requests to the backend directly via Swagger.
For most endpoints you have to be authenticated for them to work.
In Swagger you can do this like the following:

Open the API documentation.
If you try to execute the seeds GET request now it should return error 401.
Click Authorize.
Use the variant with header oauth2 (OAuth2, authorizationCode).
Enter the client_id. You have to use a different one depending on the location:
- Production: PermaplanT-Prod.
- MR: PermaplanT-MR.
- Dev: PermaplanT-Dev.
- Local:
  - local-swagger-ui if you use the preconfigured Keycloak instance.
  - If you configured Keycloak yourself you have to create a client matching the URL.
Enter your user credentials.
You should now be able to execute a request in Swagger.

HTTP Headers

This document explains the HTTP request headers used by the backend.

Authorization

The Authorization header is used for authentication/authorization. The access token should be set either by the frontend or manually when making requests with for example curl.

For instructions on obtaining and using an access token, refer to this document.

Language etc.

Are not sent nor used, as the backend is agnostic to it.

Cronjobs

Cronjobs in the backend can be added in the function start_cronjobs in the main.rs file.
This should be done by spawning a new tokio thread via tokio::spawn(cronjob_function());.

The function itself should never return.
This can be done by using the following function signature fn cronjob_function() -> ! and using a loop inside the function itself.

Example database cronjob:

#![allow(unused)]
fn main() {
pub async fn cleanup(pool: Pool) -> ! {
    loop {
        tokio::time::sleep(Duration::from_secs(60)).await;

        let query = diesel::delete(<some_constraint>);
        debug!("{}", debug_query::<Pg, _>(&query));

        match pool.get().await {
            Ok(mut conn) => match query.execute(&mut conn).await {
                Ok(delete_rows) => log::info!("Removed {delete_rows} entries"),
                Err(e) => log::error!("Failed to execute query: {}", e),
            },
            Err(e) => {
                log::error!("Failed to get connection from pool: {}", e);
            }
        }
    }
}
}

Performance Benchmarks

Requirements

The following tools are required to run the benchmarks:

docker
nushell (e.g. via cargo install nu)
perf (package might be called linux-perf-5.10)
flamegraph (cargo install flamegraph)
httperf
jq
psql (part of PostgreSQL)
standard linux tools like grep, awk etc.

Setup

Add the following to the end of backend/Cargo.toml. This is necessary to ensure that perf can accurately track the function stack.

[profile.bench]
debug = true

The benchmarks/backend/*/setup.sh scripts contain PERF=/usr/lib/linux-tools/5.4.0-153-generic/perf to set the location of perf. Depending on your distribution it might or might not be needed to change this. On Debian no change is needed. Otherwise modify the path to point to your perf installation.

Scripts

You can find the scripts in benchmark/backend/. They are supposed to be run from the repository's root folder.

The subfolders contain scripts to run performance benchmarks in specific endpoints.

`setup.sh`

Execute it as follows:
./benchmarks/backend/<endpoint>/setup.sh <username> <password>.

The database and backend have to be started manually. Depending on the endpoint it might execute insert_data.sh scripts to insert additional data into the database.

The script might output instructions while executing. Follow these instructions to ensure the benchmark works correctly.

Parameters:

username: Your PermaplanT username for https://auth.permaplant.net.
password: Your PermaplanT password.

`run_httperf.sh`

Execute like the following:
./benchmarks/backend/<endpoint>/run_httperf.sh <username> <password> <number_of_requests> <request_rate>.

This script shall be run as soon as the setup.sh starts the backend via cargo flamegraph.
It will execute requests on the backend using httperf.

Once this script finishes you can interrupt setup.sh via Ctrl+C. Note that it might take 20min or longer to finish once interrupted. Do not press Ctrl+C again, otherwise the generated flamegraph will not include all data.

Parameters:

username: Your PermaplanT username for https://auth.permaplant.net.
password: Your PermaplanT password.
number_of_requests: The total number of requests httperf will execute (e.g. 10000).
request_rate: How many requests will be executed per second (e.g. 100).

`get_statistics.sh`

Execute like the following:
./benchmarks/backend/<endpoint>/get_statistics.sh.

This script shall be executed once all previous scripts finished.
It will parse the PostgreSQL logs and httperf logs to extract execution times.

Example run

The following is a step by step guide on how to execute the benchmark for the heatmap:

Insert
```
 [profile.bench]
 debug = true
```
into Cargo.toml.
Execute: ./benchmarks/backend/heatmap/setup.sh <username> <password>. Do the following once the script gives the instructions.
- Start the backend in dev mode.
- Press Enter.
- Select map size: press s.
- Stop the backend.
- Press Enter.
Wait for the backend to start in release mode.
Once its started execute in a second shell: ./benchmarks/backend/heatmap/run_httperf.sh <username> <password> 100 10
Wait for httperf to finish.
Press Ctrl+C in the setup.sh shell.
Wait until flamegraph.svg was generated (this might take 20min or longer). If you interrupt this step you have to rerun the benchmark.
Execute: ./benchmarks/backend/heatmap/get_statistics.sh
Collect results:
- flamgraph.svg
- Copy request execution times and query execution times from stdout of get_statistics.sh

Why do we need the `schema.patch` file

When executing diesel migration run diesel connects to the database and expresses the current schema of the database in the schema.rs file. The config for this mechanism is in diesel.toml. You can use diesel print-schema to output the schema manually. Unfortunately Diesel generates type definitions for types we import from Postgis. This results in a double use:

diesel::table! {
    use postgis_diesel::sql_types::Geography; // <-- even though we import using --import-types
    use super::sql_types::Geography;          // <-- this gets generated by Diesel

After generating the schema.rs file Diesel applies the patch file to it.

When to update the `schema.patch` file

Whenever you get an error message similar to error applying hunk #2 you have to update the schema.patch file. This happens when schema.rs changes in the diff context of the patch file (the lines before and after the change).

How to update the `schema.patch` file

The following is done relative to the backend directory.
```
cd backend
```
Comment out the following line from diesel.toml:
```
patch_file = "src/schema.patch"
```
You can prepend the line with '#'.
Get a clean database with all migrations:
```
diesel database reset
```
You should now have a generated schema.rs in the src directory.
Copy the schema.rs file to schema_tmp.rs.
```
cp src/schema.rs src/schema_tmp.rs
```
Make the necessary changes to schema_tmp.rs.

Look at the existing schema.patch to see what needs to change.

Create a new patch file.

diff -U6 src/schema.rs src/schema_tmp.rs > src/schema.patch

Add patch_file = "src/schema.patch" to the diesel.toml again.
Delete schema_tmp.rs.

From now on the newly generated patch file is used by Diesel.

Steps to add a Field to Entities

Create a migration
cd backend && diesel migration generate my_new_migration
This will create up.sql and down.sql inside a new migration folder under /backend/migrations/
up.sql should create all necessary tables, columns, constraints as well as modify data if necessary
down.sql should undo all changes from up.sql
Run the migration
make migration
During development you can run make migration-redo to run down.sql and up.sql of the most recent migration
Add new field to Entity
e.g. extend the Plants entity in entity.rs
(Optional) Update the schema patch
If you see an error message similar to error applying hunk #2, you will have to update schema.patch
Add field to DTOs (where applicable)
e.g. extend PlantsSummaryDto in dto.rs
Update usages and trait implementations of DTOs (where applicable)
e.g. implementation of the From Trait for PlantsSummaryDto in plants_impl.rs
IMPORTANT: The order of the fields in the DTOs must be the same as in the corresponding entity.
Update database schema documentation
Review the documentation under /doc/database/schemata and make the necessary changes.
Extend API documentation
Review the swagger API documentation under http://localhost:8080/doc/api/swagger/ui/
For better understanding of the API endpoints that uses the modified DTOs, consider adding an #[schema(example = "...")] attribute macro to the DTO
For example:

pub struct TimelineDto {
    #[schema(example = "{ \"2020\": { \"additions\": 7, \"removals\": 7 } }")]
    pub years: HashMap<String, TimelineEntryDto>,
    [...]
}

Changelog

All notable changes for developers or end users will be documented in this file.

Use a not-yet-used-in-any-PR random line in the top-most version.

Syntax: - KEYWORD: short text describing the change _(Your Name)_

The (optional) keywords are:

MIGRATION: if a new migration was added
SCRAPERDATA: if a new deployment of scraper data is needed
ENDPOINT: if an endpoint changed in an incompatible way
CI: if CI scripts changed

UNRELEASED

CI: added new changelog for 0.4.2 (Filip Markovic)
CI: fix dev e2e and import scraper data (Filip Markovic)
()
()
()
()
()
Update documentation of frontend architecture (Daniel Steinkogler)
()
()
()
Implement map deletion (Moritz Schalk)
Document frontend testing strategy (Moritz Schalk)
()
Reset size of new maps to old size (Andrei Dinu)
Update frontend packages (Andrei Dinu)
()
Place HeatmapLayer to always be positioned directly below PlantsLayer (Daniel Steinkogler)
()
()
()
Add first draft of hydrology layer in frontend (Lukas Anton Lakits)
()
Fix migration regarding non-nullable notes (Jannis Adamek)
Add BasicAttributeEditForm for abstraction of add-date and remove-date (Lukas Anton Lakits)
Add tests for all actions (Lukas Anton Lakits)
()
Extract tests for plant layer actions into own file and add additional tests (Lukas Anton Lakits)
()
MIGRATION: Add migrations for crop rotation named temporal relation (Lukas Anton Lakits)
Add notes (left toolbar) to drawing & shading layers (Lukas Anton Lakits)
Fix test for base layer actions (Lukas Anton Lakits)
()
SCRAPERDATA: Extend scraper for importing for crop rotation data (Lukas Anton Lakits)
()
()
Enable pagination on map overview screen (Moritz)
()
Rename plant relations to spatial relations (Lukas Anton Lakits)
()
Add width to left toolbar for all plants (Lukas Anton Lakits)
CI: fix pre commit in pipeline (Filip Markovic)
CI: fix changelog check for dev (Filip Markovic)
()
()
Add life_cycle to plants API (Jannis Adamek)
()
Fix map delete button title attribute. (Christoph Schreiner)
Mark WIP migrations and update release documentation (Christoph Schreiner)
Changed heatmap algorithm and backend to use traffic light colors (Christoph Schreiner)
()
()
Added tile view for file selector (Daniel Steinkogler)
Fix placing images in Drawing Layer (Daniel Steinkogler)
()
()
Add GitLab template for "release" (Andrei Dinu)
()
()
Improve performance of heatmap algorithm (Christoph Schreiner)
()
Enable map deletion (Moritz)
()
Fix E2E test failure caused by changed username input label (Christoph Schreiner)
()
()
Prevent placing plants when timeline is loading (Daniel Steinkogler)
()
()
CI: add db reset and e2e tests to dev (Filip Markovic)
()
()
Refactor selection of elements (Daniel Steinkogler)
Implement measurement mode (Moritz)
()
()
()
()
Draw new drawings in separate layer (Daniel Steinkogler)
()
()
()
()
()
()
()
()
()
()
()
()
()
Add demo brush implementation (Daniel Steinkogler)
Add notes to shadings same as plantings and drawings (Jannis Adamek)
Update usecases (Moritz)
Add x and y offset to base layer (Jannis Adamek, Moritz)

0.4.2 - 02.08.2024

Reset size of new maps to old size (Andrei Dinu)
Update documentation of frontend architecture (Daniel Steinkogler)
CI: remove console.log before deployment (Filip Markovic)
Fix migration regarding non-nullable notes (Jannis Adamek)
Enable pagination on map overview screen (Moritz)
CI: fix pre commit in pipeline (Filip Markovic)
CI: fix Jenkinsfile.release for release (Filip Markovic)
Added tile view for file selector (Daniel Steinkogler)
Fix placing images in Drawing Layer (Daniel Steinkogler)
Get use cases done (Daniel Steinkogler)
Add GitLab template for "release" (Andrei Dinu)
CI: pump version and fix security issues (Filip Markovic)
Prevent placing plants when timeline is loading (Daniel Steinkogler)
Implement measurement mode (Moritz)
Draw new drawings in separate layer (Daniel Steinkogler)
Updated database documentation (temmey, Christoph Schreiner)
CI: check pipeline stability (Filip Markovic)
Fix the bug where fill patterns are not correctly rendered in Firefox (Daniel Steinkogler)
Add x and y offset to base layer (Jannis Adamek, Moritz)
Enable map search in Frontend (Moritz Schalk)
CI: add pr -> mr docs and show mr version on mr.permaplant.net (Filip Markovic)
Add notes to drawings to match plantings. #close 1385 (Jannis Adamek)
Add missing authors to doc/authors.md (Lukas Anton Lakits)
Added missing contributors and updated texts on landing page (Stefanie Feldmann)
Updated landing page order and added slider to blog posts (Stefanie Feldmann)
Fixed some spelling errors in the shade layer info text (Stefanie Feldmann)

0.4.1 - 29.05.2024

CI: added pipeline for master.permplant.net and other name changes for pages (Filip Markovic)
Added Meeting Agenda&Notes for 15.04.2024 9:00 (Markus Raab, Daniel)
Added Meeting Agenda&Notes for 22.04.2024 9:00 (Markus Raab, Christoph)
Added Meeting Agenda&Notes for 05.05.2024 9:00 (Markus Raab, Lukas)
Added Meeting Agenda&Notes for 13.05.2024 9:00 (Markus Raab, Jannis)
Added Meeting Agenda&Notes for 20.05.2024 9:00 (Markus Raab, Moritz)
Add auditability metadata to plantings and maps (Jannis Adamek)
When creating plantings set remove_date according to life_cycle. #close 724 (Jannis Adamek)
Users can now create, update, rename, reorder and deleted layers. #close 1336 (Jannis Adamek, Daniel Steinkogler)
Add notes to drawings to match plantings (Jannis Adamek)
Removed Blossoms from Frontend (Text from guided tour, awarding Blossoms at the end of the tour) (Andrei Dinu)
Added templates for Issues and Merge Requests in GitLab, removed GitHub folder (Andrei Dinu)
Adjusted size and position of initial view of map, as well as default map polygon, to have entire map in view by default (Andrei Dinu)
Fixed tour skipping steps related to timeline, corrected text entries for tour related to timeline. (Andrei Dinu)
Fixed warning text from left toolbar being cut by map elements. (Andrei Dinu)
Added paragraph about z-index usage to Frontend UI Usability Guideline in Docs (Andrei Dinu)
Scraper: Error message of missing csv files now contains file name (Christoph Schreiner)
Make plant labels the same size regardless of zoom level (Moritz Schalk)
Add tests for hooks in frontend/layers (Lukas Anton Lakits)
Add automatic scroll pagination to plant search (Lukas Anton Lakits)
Add warn signs to sizes for multi-selected plant-areas (Lukas Anton Lakits)
Add tutorial for creating new layers in Frontend (Lukas Anton Lakits)
Change keybindings (entf) from delete to remove (Lukas Anton Lakits)
Add use case for crop rotation (Lukas Anton Lakits)
Increase debounce submit delay (Lukas Anton Lakits)
Change style of selected tabs in drawing layer right toolbar (Lukas Anton Lakits)
Disable flipping of elements on map (Lukas Anton Lakits)
Add points in middle of bezier polygon (Daniel Steinkogler)
Return 409 Conflict when creating a map with taken name (Jannis Adamek)
CI: take mdbook from gitlab (Filip Markovic)
Provide specific toast message to user when backend returns 409 conflict for map with taken name (Andrei Dinu)
Add toast messages for actions failing (Andrei Dinu)
Change error texts to make translation of "sorry" consistent (Andrei Dinu)
Automatically focus created text label after creation (Daniel Steinkogler)
Hide transformer handles when editing bezier polygons (Daniel Steinkogler)
CI: avoid cargo index rebuild (Filip Markovic)
CI: change cleandb.py script to avoid confusion in pipeline errors (Filip Markovic)
Add manual test for 0.4.1 release (Filip Markovic)
Fixed bug to re-enable Ctrl+A in text inputs (Daniel Steinkogler)
CI: implement changes for new branch system into Jenkinsfile (Filip Markovic)
Fix drawing issues with overlapping bezier polygons (Daniel Steinkogler)
CI: re-enable and try to fix E2E tests (Filip Markovic)
change mentions of Github Permaplant to Gitlab (Filip Markovic)
Increase cargo net.retry configuration to handle random network errors during CI. (Christoph Schreiner)
Disable selection of other shapes when editing bezier polygon (Daniel Steinkogler)
Fix timezone issue when calculating timeline data (Daniel Steinkogler)
Added fill patterns, labels and images to drawing layer (Daniel Steinkogler)
Prevent removal of plants and drawings on addDate with keybinding (Lukas Anton Lakits)

0.4.0 - 12.4.2024

Display lines at y=0 and x=0 on the grid. (Moritz)
Fix a bug that caused the yard stick to jump around while zooming the map (Moritz)
Implement a heatmap that shows which locations are most suited for a specific plant (Gabriel, Paul, Moritz)
needs new migrations
needs new scraper data (integer for plant spread and height)
pin python package versions for e2e tests #1200 (4ydan)
Remove variety from table seeds (Jannis Adamek)
Add timeline API that summarizes plantings #967 (Jannis Adamek)
Add migration to add drawing layer to existing maps #1234 (Jannis Adamek)
Refactor react query error handling (Daniel Steinkogler)
Add notes to plantings in backend #1156 (Jannis Adamek)
Fix seed routes and add naming convention guideline (Daniel Steinkogler)
Enable automatic image scaling in base layer (Moritz)
changed release name from 0.3.7 to 0.4.0 (Filip Markovic)
Add guideline and decisions for key handling) (Daniel Steinkogler)
Fix ref warning in PlantLabel, center labels as intended (Paul)
Fix planting cursor preventing the placement of an area of plants (Paul)
Refactor nearly all api calls to idiomatic react query (Paul)
Add an area of plant indicator (Paul)
CI: fixed bug for release in Jenkinsfile.release (cargo doc not running in backend folder) (Filip Markovic)
Added Meeting Agenda&Notes for 20.10.2023 9:00 (Markus Raab, Samuel)
Added Meeting Agenda&Notes for 27.10.2023 9:00 (Markus Raab, Jannis)
Added Meeting Agenda&Notes for 04.12.2023 9:00 (Markus Raab, Daniel)
Added Meeting Agenda&Notes for 11.12.2023 9:00 (Markus Raab)
Added Meeting Agenda&Notes for 18.12.2023 9:00 (Markus Raab, Christoph)
Added Meeting Agenda&Notes for 27.12.2023 9:00 (Markus Raab, Daniel)
Added Meeting Agenda&Notes for 02.01.2024 9:00 (Markus Raab, Daniel)
Added Meeting Agenda&Notes for 08.01.2024 9:00 (Markus Raab, Christoph @chr_schr)
Added Meeting Agenda&Notes for 15.01.2024 9:00 (Markus Raab, Moritz)
Added Meeting Agenda&Notes for 22.01.2024 9:00 (Markus Raab, Daniel)
Added Meeting Agenda&Notes for 29.01.2024 9:00 (Markus Raab, Jannis)
Added Meeting Agenda&Notes for 05.02.2024 9:00 (Markus Raab, Christoph)
Added Meeting Agenda&Notes for 12.02.2024 9:00 (Markus Raab, Christoph)
Added Meeting Agenda&Notes for 19.02.2024 9:00 (Markus Raab, Daniel)
Added Meeting Agenda&Notes for 11.03.2024 9:00 (Markus Raab, Jannis)
Added Meeting Agenda&Notes for 25.03.2024 9:00 (Markus Raab, Moritz)
Added Meeting Agenda&Notes for 02.04.2024 9:00 (Markus Raab, Lukas)
Added Meeting Notes for 04.04.2024 14:00 (Andrei Dinu)
Added Meeting Agenda&Notes for 08.04.2024 9:00 (Markus Raab, Filip)
Add 'Christoph Schreiner' as team member (Christoph Schreiner)
Migrate from Jest to Vitest, update Vite to v5, update Node to 20, .env should be .env.local (Paul)
Fix broken .env reading for scraper (Paul)
Add a dev env variable for react query when developing in offline env (e.g. plane) (Paul)
Collect events from planting layer and add it to timeline (Daniel Steinkogler)
Flatten bezier polygon line after deleting point (Daniel Steinkogler)
Remove error messages in console if a seed was not found (Moritz)
Add drawing layer functionality including rectangles, ellipses, lines and bezier polygons (Daniel Steinkogler, Jannis Adamek)
Landing page: Added blog entries, updated team members, minor text changes (Christoph Schreiner)
Fix the markdown so that mdbook tests pass (Daniel Steinkogler)
Improved the scraper: Fixed a bug and improved cleaning for German common names (temmey)
Scraper: Separate fetching of German common names from merging datasets (Christoph Schreiner)
Scraper: Allow applying overrides to merged dataset (Christoph Schreiner)
Make map geometry viewable and editable (Moritz)
Improve documentation of schema.rs patch workflow. (Jannis @horenso, Christoph @chr_schr)
Prevent propagating enft key on markdown editor (Daniel Steinkogler)
Enable deletion of selected plants via DEL shortcut (Daniel Steinkogler)
Refactoring of timeline state and add unit tests (Daniel Steinkogler)
Fix link to Plant image for Openstreetmap (Andrei Dinu)
Add key combinations for map geometry (Daniel Steinkogler)
Add documentation for adding a new field to an entity (Christoph Schreiner)
Add tooltips to show keybindings (Daniel Steinkogler)
Use arrow keys to navigate between timepicker sliders and fix timeline performance issues (Daniel Steinkogler)
Use integer for plant spread and height (Christoph Schreiner)
Increased zoom scaling factor for Map Editor / faster zooming (Samuel)
Added PermaplanT logo to link previews in meta tag and replaced default React logo (Andrei Dinu)
wrap api queries using react query (Daniel Steinkogler)
CI: running pr deployment only on pr and not master branch (Filip Markovic)
CI: unstash schemas in release pipeline in build-backend (4ydan)
CI: added check if schema.rs changes in remigration (Filip Markovic)
CI: updated unsafe packages for release & fixed release github template (4ydan, Filip Markovic)
Fixed German common names not being used when language is set to German (Christoph Schreiner)
added manual testing for 0.3.7 (successful) (Filip Markovic)
Fixed map label and common name capitalization issues (Christoph Schreiner)
fixed broken tour and blog date for release (Filip Markovic)
CI: added deployment of doc and README links to doc (Filip Markovic)
Add decision for polygon libraries (Daniel Steinkogler)
Added keybindings for undo and redo (Daniel Steinkogler)
E2E: fix planting cursor tests (4ydan & absurd-turtle)
Added planting notes to planting details (Daniel Steinkogler)
CI: mark duplicate code (4ydan & Filip Markovic)
Added keybinding configuration for macOS (Daniel Steinkogler)
Up the rust version to 1.74 (4ydan)
Display a rectangle for area of plantings (Paul)
Refactor the planting api to batch processing (Paul, Jannis)
Area of plants resizing. Rename width & height of plantings to size_x & size_y. Remove scale from plantings. (Paul)
Refactor transformer into a separate store (Paul)
Replace old date picker with new timeline component using sliders to select date (Daniel Steinkogler)
Fix broken dark mode for LanguageSwitcher, SelectMenu & PaginatedSelectMenu (Lukas Anton Lakits)
Fix validation in PlantingAttributeEditForm for multi-selected plants and areas (Lukas Anton Lakits)
Fixed small issues in the documentation (typos/links/phrasing) (Andrei Dinu)

0.3.6 - 21.11.2023 (151 commits)

Add guideline and decisions for key handling) (Daniel Steinkogler)
Plantings now store seed information if they were created using a seed (Moritz)
Tooltips show the full plant for plantings that were created using a seed (Moritz)
Refactor base layer toolbar using react hook form (Moritz)
fixed: slider displays wrong value after toolbar resize (Samuel)
Added Meeting Agenda&Notes for 13.11. 9:00 (Markus Raab, Adi)
Hamburger menu opens a full page navigation on small viewports (Samuel)
Fix regression where Full plant names are not shown (Moritz)
CI: disable E2E tests in master #1055 (4ydan)
Close modals with escape #1027 (Daniel Steinkogler)
Display the plant icon next to the cursor in placement mode (Samuel)
Plant layer is selected per default (Samuel)
E2E: Increase e2e timeline/baselayer test stability, replace timeouts with sleep #1010 (4ydan)
Release: npm audit fix #1077 (4ydan)

0.3.5 - 06.11.2023 (320 commits)

Calculation of scaling now fixed, please (auto)scale your map again.
Fix similar toasts appearing multiple times on screen (Moritz)
Fix browser browserlists #954 (4ydan)
Decide about which use cases to include for 1.0 (Markus Raab and Yvonne Markl with the help of PermaplanTeam)
Enable automatic image scaling in base layer (Moritz)
Add concept for key handling (Daniel Steinkogler)
Refactor keybindings according to new keybinding concept (Daniel Steinkogler)
Plantings now store seed information if they were created using a seed (Moritz)
Tooltips show the full plant for plantings that were created using a seed (Moritz)
Decide about which use cases to include for 1.0 (Markus Raab and Yvonne Markl with the help of PermaplanTeam)
Plantings now store seed information if they were created using a seed (Moritz)
Tooltips show the full plant for plantings that were created using a seed (Moritz)
Enable seed search in plant layer (Moritz)
Finish seed use case (Moritz)
Add decision for api mocking tool (Daniel Steinkogler)
Rename section "Seeds" to "Inventory" (Moritz)
Added Meeting Agenda&Notes for 23.10. 9:00 (Markus Raab, Daniel Steinkogler)
Added Meeting Agenda&Notes for 30.10. 9:00 (Markus Raab, Christoph N.)
add decision for timeline concept (Daniel Steinkogler)
Improve UI and responsiveness of file selector #1011 (tschawax)
Add frontend UI and usability guide #918 (tschawax)
Improve wordings, usability and UI of guided tour #871 (tschawax)
Fix tour-completion logic of cancel-confirmation dialog in guided tour #986 (tschawax)
Improve styling of login and logout button #983 (tschawax)
Add horizontal scrolling to toolbars #981 (tschawax)
Improve vertical scrollbar behaviour #970 (tschawax)
Split and rewrite copy & paste usecase #1 (tschawax)
Create remember-viewing-state usecase #1 (tschawax)
Create multi-select usecase #1 (tschawax)
Fix transformer rotation handle and moving selected plants #1013 (tschawax)
Clean up the asset file structure in frontend (Moritz)
Implement multi-select usecase #727 (tschawax)
Fix plant deletion in guided tour on small screens #861 (tschawax)
Enable ctrl, shift, command to modify selection #979 (tschawax)
Fix tooltips on plant hovering in multi selection #1033 (tschawax)
Add status-specific toolbox icon design and add toolbox icon support to icon button component #1025 (tschawax)
Improve design and behavior of undo/redo icons and improve focus design #657 (tschawax)
Added Meeting Agenda&Notes for 06.11. 9:00 (Markus Raab, Moritz)
Added Meeting Agenda&Notes for 23.10. 9:00 (Markus Raab, Daniel Steinkogler)
Added Meeting Agenda&Notes for 30.10. 9:00 (Markus Raab, Christoph N.)
Enable planting a field of a plant #1039 (tschawax)
Add status-specific toolbox icon design and add toolbox icon support to icon button component #1025 (tschawax)
Improve design and behavior of undo/redo icons and improve focus design #657 (tschawax)
Replace notes field in create seed form with markdown editor (Daniel Steinkogler)
Improve dark mode design of danger variant buttons #1029 (tschawax)
Improve loading spinner size in file selector and improve file selector responsiveness #1026 (tschawax)
Improve tooltip wordings of toolbox icons and extract them into new single file #1028 (tschawax)
E2E: Refactor data-testid according to naming convention (4ydan)
pump versions (4ydan)
CI: Run e2e tests on dev.permaplant (4ydan)

0.3.4 - 14.10.2023 (203 commits)

Exit planting mode with escape (Daniel Steinkogler)
Renaming of layer list components (Daniel Steinkogler)
Fix ordering of seeds by expiration date (Moritz)
Re-enable seed search. It will now take the entire plant name into account. (Moritz)
Make plant names in select menu more consistent with seed overview (Moritz)
Doc: refinement of timeline use cases (Daniel Steinkogler)
Rectify order of name parts in plant names (Moritz)
Added Meeting Agenda&Notes for 18.9. 9:00 (Markus Raab, 4ydan)
Added Meeting Agenda&Notes for 25.9. 9:00 (Markus Raab, Moritz)
Added Meeting Agenda&Notes for 2.10. 9:00 (Markus Raab, Daniel)
Added Meeting Agenda&Notes for 9.10. 9:00 (Markus Raab, Christoph)
Update seed use case (Moritz)
Implement central facilities for displaying plant names (Moritz)
Make sure that two seeds can't have the same combination of user, name and plant (Moritz)
Restrict seed names to make complete names less confusing (Moritz)
Fix "harvest year" column title wrapping inappropriately (Moritz)
Make resetting in search input component cross-browser compatible and adapt resetting of search results #761 (tschawax)
Update Zustand documentation #957 (tschawax)
Fix dead end of step 8 of plants layer in guided tour #955 (tschawax)
Doc: Reduce e2e entry barriers #917 (4ydan)
Fix textarea not allowing more than one line of text (Moritz)
E2E: Increase click on canvas robustness (4ydan)
Fix cargo deny check (4ydan)
Fix: release pipeline mdbook build stage (4ydan)
Improve Makefile #681 (4ydan)
CI: Tag docker images #931 (4ydan)

0.3.3 - 15.09.2023 (536 commits)

Archive seeds instead of deleting them (with undo) #872 (Moritz)
Expand seed overview with additional table fields (Moritz)
Updated UC for guided tour and gaining blossoms (Thorben)
Added a cancel confirmation to the editor tour (Thorben)
Finish documentation of custom UI elements (Moritz)
Fix seeds being set to Indian Abelia after edit (Moritz)
Order seeds by use by and harvest year (Moritz)
Add toggleable plant labels (Moritz)
Fix various validation bugs in seed form (Moritz)
Link seeds page in the navbar (Moritz)
Disable seed search (Moritz)
Enable seeds to be edited and deleted (Giancarlo & Moritz)
Update UC for timeline and plants layer (Paul)
Fix bug in updating of the plant selection (Paul)
Added Meeting Agenda for 28.8. 9:00 (Markus Raab)
Added Meeting Agenda for 4.9. 9:00 (Markus Raab)
Added Meeting Agenda for 11.9. 9:00 (Markus Raab)
update doc/database/hierarchy.md to clarify how we render plant names (temmey)
updated sqlfluff config, remove unused .sql files (temmey)
Add Christoph Nemeth as Teammember (tschawax)
Fix middle mouse button to only move the stage or select individual plants #817 (tschawax)
Fix selections being kept after choosing a plant from the search list #787 (tschawax)
Fix placing new plants onto existing plants #890 (tschawax)
Fix select box while being in placement mode #886 (tschawax)
Fix selecting invisible plants #805 (tschawax)
Seeds: translate quality and quantity columns (Moritz)
Fix drag select not working and add appropriate e2e regression tests #852 (4ydan & Moritz)
CI: Update doc (4ydan)
Doc: Update testing strategy #864 (4ydan)
E2E: Add new e2e test for undoing deletions #889 (4ydan)
E2E: Seeds tests (4ydan)
CI: Add changelog test to CI, only in PR stages #857 (4ydan)
E2E: Worker uuids fixture #837 (4ydan)
GIT: Add data analysis jupyter notebook #843 (4ydan)
MDB: Fold all chapters #818 (4ydan)
CI: Add codespell pre-commit #811 (4ydan)
E2E: Add base layer tests #777 (4ydan)
E2E: Add timeline tests #796 (4ydan)
E2E: Add layer visibility tests #797 (4ydan)

0.3.2 - 07.08.2023 (42 commits)

Fix a bug where an 'empty' but visible selection box would be left behind (Paul)
Fix a bug where seemingly random date change actions would be fired (Paul)
Fix dimensions of canvas (Paul)
npm audit fix + test protocol (Markus)
E2E: Add undo/redo e2e tests # (4ydan)
E2E: Improve documentation/usage #784 (4ydan)

0.3.1 - 03.08.2023 (54 commits)

Added a cancel confirmation to the editor tour (Thorben)
Disabled retry on Nextcloud plant icons in PlantSearch (Samuel)
Commented out disabled buttons for user study (Samuel)
Basic baseLayerConfig validation - fixed bugfix/734-base-layer-image-gets-lost (Samuel)
Fix a bug where texts in the editor tour were swapped (Thorben)
Map: Remove Step/History info #745 (4ydan)
E2E: Add planting e2e tests #766 (4ydan)
E2E: Add plant search e2e tests #751 (4ydan)
CI: Add most of pre-commit hooks to sanity stage #736 (4ydan)

0.3.0 - 28.07.2023 (273 commits)

Added Guided Tour for the Map Editor (Thorben)
Remove error toast when adding a plant without an icon in Nextcloud. (Moritz)
commented out properties in table plants for now to improve build time. (temmey)
set all enums in DB to lowercase (temmey)
added component to display plant names correctly formatted (temmey)
fixed issues with correctly displaying plant names (temmey)
Add grid functionality. (Moritz)
sizes of plant in map editor depend on their spread value (temmey)
Handle events of same user, discard events in same tab (Paul)
Fix a bug in the date handling actions of plants (Paul)
updated scraper to translate spread&height into new enum types (temmey)
Add debouncing to base layer toolbar (Moritz)
Fix a bug in loading images (Paul)
Fix a bug where the wrong value is assigned to an input field (Moritz)
Give feedback when plant search is empty (Moritz)
Display icon in plant search if available. (Moritz)
DEV: squashed migrations (temmey)
DEV: start using sqlfluff in pre-commit (temmey) and Benjamin
CI: Improve pipeline parallelization #577 (4ydan)
CI: Add groovy pre-commit hook #685 (4ydan)
CI: Optimized mdbook docker image #585 (4ydan)
CI: Test diesel migrations in PR and master #134 (4ydan)
CI: Remove cargo check, put clippy before doc #688 (4ydan)
E2E: login/logout e2e tests #625 (4ydan)
E2E: map creation e2e tests #707 (4ydan)

0.2.3 - 18.07.2023 (165 commits)

integrated FileSelector in BaseLayer (Samuel)
introduced file selection components to select and upload Nextcloud files (Samuel)
Finish implementation of seed search (Moritz)
A timeline date can be set and changed by a date picker. Plantings exist relative to a date. (Paul)
The add/remove date of plants can be changed in the toolbar. (Paul)
Added zod as form validation library. (Paul)
Finish implementation of seed search (Moritz)
CI: Check package-lock.json #597 (4ydan)
Further Makefile targets #630 (4ydan)
DOC: Improve manual test case docu (4ydan)
CI: mdbook linkchecker policy set to error #628 (4ydan)
Up webdav to 5.2.2 and vite to 3.2.7 due to security issues #629 (4ydan)
backend: add endpoint to generate the heatmap (Gabriel)
UX: Revised existing error notifications and added new ones for other API calls (Thorben)
backend: add scheduled task to remove maps #90 (GabrielThorben)

0.2.2 - 12.07.2023 (282 commits)

Added Nextcloud integration documentation in /doc/research/nextcloud_integration.md(Samuel)
Fix wrong placement of plantings (Paul)
CI: Send email when master fails #109 (4ydan)
CI: Add link checker to CI pipeline #555 (4ydan)
Fix bug in relations (Paul)
UI: Added hover tooltip to edit map button (Thorben)
UX: Revised existing error notifications and added new ones for other API calls (Thorben)
Remove anchors to prevent nonuniform scaling of elements (Paul)
CI: Cancel previous builds #557 (4ydan)
CI: Parallel stage: fail fast & timeout & deleteDir #591 (4ydan)
Display version number on the navbar and move github link #574 (4ydan)
Improved user visible texts in map editor (Thorben)
DEV: Makefile added #549 (4ydan)
added plant relations import script to scraper (temmey)
added Christoph Kraus as Teammember (temmey)

0.2.1 - UNRELEASED (1024 commits)

Test strategy written (4ydan)
CI: Storybook/Typedoc build and stashed in Jenkins pipeline PR/Master/Release #438 (4ydan)
DOC: Fix broken links #554 (4ydan)
CI: Devcontainer support #552 (4ydan)
CI: Added mdbook build to pipeline (4ydan)
DEV: Small devcontainer improvements #563 (4ydan)
DEV: Issue forms added. #537 (4ydan)

0.2.0 - 29.06.2023

Nextcloud Konva image component: can be used to create image items on a layer (Samuel)
Nextcloud image gallery including Nextcloud image components for unauthenticated and authenticated use, Nextcloud utilities for fetching data from Nextcloud public share (Samuel)
most of discussed UI/UX improvements done: disabled icons, tooltips for buttons in left bar, tooltips for plants, images for plants, notification border color, select one plant of selection for attribute editor (needs some polishing still) (Paul and Samuel)
Fetch corresponding layer IDs of a map during initialization of the map editor (Paul and Thorben)
Use the correct layer ID for create and fetch actions (for plantings) in the map editor, enabling the possibility for multiple independent maps (Paul and Thorben)
Location picker map in map creation form only loads after actively pressing a button (Thorben)
Maps can be duplicated from the map overview (in PR #515) (Thorben)
Login use case done. (Gabriel and Samuel)
Layers visibility use case done. (Samuel)

0.1.0 - 19.04.2023

Created Landingpage (PermaplanTeam)

CI/CD Pipeline

Triggers

The pipeline will be executed only for pushes to Pull Requests and for pushes to master.

If the pipeline fails and you think it is not the fault of your code, you can re-execute the pipeline by typing jenkins build please as a comment. If problems persist, please create a new issue with the failing build log.

For users with login credentials for Jenkins, you can manually execute the pipeline for a branch or pull request via the Jenkins UI. Please ask if you need login data.

Succeeding Pushes

If you push to branches:

Only the newest commit will be built. It does not matter if commits in between would pass.
Builds of older pushes are aborted.
Also jenkins build please will abort previous builds and start the build again.
The latest MR build job will stay deployed on (https://mr.permaplant.net).
The master branch is excluded from these rules.

Stages

Sanity stage

This stage performs rapid checks like pre-commit, migrations and schema building.

Local pre-commit currently does not perform the codespell hook, but it is performed in the pipeline. Cargo fmt, eslint and groovy linting is not performed through pre-commit.

Tests and Build

This is a parallel stage which fails fast (exits if one stage fails) or times out after 2 hours.

It can be subdivided in following categories:

Multiple parallel cargo stages

Standard cargo build, clippy, doc and test is performed here.

One sequential frontend stages

Frontend is built, tested, linted, format checked and additionally package.json version is verified to be up to date. Storybook and typedocs are also generated here.

One sequential mdbook stages

Mdbook is built, tested and links are checked.

Deploy MR

Every pull request will be deployed on a publicly available instance on mr.permaplant.net. Jenkins will acquires a lock before deploying to mr.permaplant.net and release it after finishing the E2E stage. This lock prevents other jobs to overwrite the deployment while we are performing E2E tests.

Since there is only one agent for MRs available, the last built MR wins.

E2E Tests

E2E tests are run on mr.permaplant.net. When a test times out, it is retried up to two times with a five second delay between retries.

Test reports and results can be found in the jobs artifacts.

Failed tests will generate videos and/or screenshots inside e2e/test-results/ in the jobs artifacts, depending on what failed. The videos have to be downloaded to be viewed.

There is always a html report inside e2e/test-reports/ in the jobs artifacts and a cucumber report on a separate page.

Deploy Dev

The master branch will be automatically deployed to dev.permaplant.net.

Deploy Prod

There is a separate Jenkinsfile (/ci/Jenkinsfile.release) for this pipeline, which is only manually executable through Jenkins. It runs only build and deploying stages (no testing).

Production is deployed to www.permaplant.net.

See release.md for the manual release procedure.

Contributing to PermaplanT

Getting Started

Before you start anything, please make sure you:

skimmed the mdbook (make run-mdbook), especially the chapters listed in "Architecture", including:
- use cases
- guidelines
- decisions
also have a look at other documentations:
- API
- Storybook (make run-storybook)
report all problems you found during getting started, as it is essential that entry barriers get reduced

For any non-trival work, i.e., not only trivial fixes/updates in documentation or tests, there should be an underlying issue. You can create such issues yourself. Before you work on it, make sure the issue is:

clear enough described,
assigned to you and
"In Progress" in our project.

Reporting a bug

If you find a bug in the code or a mistake in the documentation, you can help us by submitting an issue to our issue tracker or you can submit a Pull Request with a fix.

If you encounter a bug then please make sure to include the following information:

The version of the code you were using.
A clear and concise description of the problem.
A minimal, self-contained code sample that reproduces the problem (if possible).
Information about the environment in which the problem occurs (e.g. operating system, version of Rust, version of Diesel, etc.)

Pre-requisites

Development

The project uses pre-commit hooks to ensure a consistent style.

Install pre-commit via pip or the package manager of you choice.
If you had husky installed before make sure to remove preexisting hooks. git config --unset core.hooksPath
Run pre-commit install.

Getting PRs merged

Once you created a PR, please request reviews, including also from @markus2330, who will usually also merge.

Please make sure you fulfilled all basics of PRs.

Commit messages should fulfill:

The first line in commit messages should be short.
From the third line you can have more elaborate descriptions of the changes.
Please refer to #issues/#PRs/@mention as useful, including closing your issues.

Branch names should be one of:

feature/<issue_nr>
bug_fix/<issue_nr>
documentation/
meeting_notes/
release/

If requested, and in any case before you start making fundamental changes, create a decision before creating a code PR.

Documentation

We have following pieces of documentation:

General information should be in the mdbook.
For the REST API we use utopia/swagger (in the backend).
For the backend we use cargo doc.
For the frontend we use storybook.

Sub-Projects

You can find more info on the development process here:

Contributing to Backend

Migrations

Create new migrations

You can generate new migrations with the diesel cli:

diesel migration generate migration_name

This will create two empty sql files that look something like this:

migrations/20160815133237_migration_name/up.sql
migrations/20160815133237_migration_name/down.sql

up.sql applies the migration and down.sql reverts the migration.

Now we have to write the migrations in the respective up.sql and down.sql files.

Examples:

-- up.sql
CREATE TABLE seeds (
  id SERIAL PRIMARY KEY,
);

-- down.sql
DROP TABLE seeds;

Apply migrations

diesel migration run

Redo migrations

This is especially useful for incremental improvements to the database. For example if you need to change one field in one of your tables, you can change it and redo the migration.

# Redo latest migration
diesel migration redo

# Or redo all migration
diesel migration redo --all

Contributing to Frontend

Project Structure

The majority of the code resides in src.

src
|
+-- components        # shared components used across the entire application
|
+-- config            # all the global configuration, env variables etc. get exported from here and used in the app
|
+-- features          # feature based modules
|
+-- hooks             # shared hooks used across the entire application
|
+-- routes            # routes configuration
|
+-- stores            # global state stores
|
+-- test              # test utilities and mock server
|
+-- types             # base types used across the application
|
+-- utils             # shared utility functions

Ultimately we develop a new feature in the features folder that contains domain specific code for a given feature.

A feature could have the following structure:

src/features/new-feature
|
+-- api         # exported API request declarations and api hooks related to a specific feature
|
+-- components  # components scoped to a specific feature
|
+-- hooks       # hooks scoped to a specific feature
|
+-- routes      # route components for a specific feature pages
|
+-- stores      # state stores for a specific feature
|
+-- types       # typescript types for TS specific feature domain
|
+-- utils       # utility functions for a specific feature
|
+-- index.ts    # entry point for the feature, it should serve as the public API of the given feature and exports everything that should be used outside the feature

The index.ts file of each feature should serve as its public API, and all elements within that feature should be exported from it. When importing elements from other features, use the feature's root directory, like this:

import { MyComponent } from "@/features/my-feature";

Avoid importing elements directly from subdirectories within a feature, like this:

import { MyComponent } from "@/features/my-feature/components/MyComponent";

Think of a feature as a library or a module that is self-contained but can expose different parts to other features via its entry point.

Component Design

Purely presentational components should be side effect free. That means they should not make any network requests or communicate with external systems.

Take of example a button component that is used as the login button.

It should not make the login request itself. It should rather have an onClick prop that is passed to it.
Neither should the login button make a request to see if the user is already logged in. It should be hidden by one of it's ancestor components.

That has the added benefit, that presentational components can be easily integrated into Storybook.

Documentation

We use Storybook to document shared components. Story files are named *.stories.tsx and should be located in the same folder as the component they are documenting. For an example please take a look in the src/components folder.

For other API documentation like Hooks and utility functions, we use TypeDoc. Run npm run doc to generate the TypeDoc documentation under src/generated/docs. The generated documentation is automatically integrated into Storybook under the menu DOCS. There is also the possibility to display additional documentation inside the DOCS menu in storybook. Such additional documentation files should be created in the src/docs directory for Storybook to recognize them. Furthermore, an additional documentation file must be a .mdx file and it has to export a header like this.

import { Meta } from "@storybook/addon-docs";

<Meta
  title="docs/<name_of_documentation_file>"
  parameters={{
    viewMode: "docs",
    previewTabs: {
      canvas: { hidden: true },
    },
  }}
/>;

Storybook will display an error if the .mdx file does not have valid MDX2 syntax.

Minimum requirements for every component:

one story file, probably with several exports for different states, see SimpleButton.stories.tsx
Document all props

Bootstrapping (Order of Execution)

The entry point for the frontend is src/main.tsx. From there three modules get imported src/Root.tsx, src/App.tsx and src/config/index.ts. All top level statements will also be executed during this module loading. This is true for the following in this order:

Environment configuration src/config/env.ts
i18n configuration src/config/i18n/index.ts
axios configuration src/config/index.ts

Map is nested the following way:

MapWrapper most outer, for all layers
Map contains toolbar etc.
BaseStage is the stage of Konva, i.e., the first Konva component and all other components are children

Helpful Links

React:

Frontend Architecture:

Modularizing React Applications

Zustand (Global State Management):

React Query (Server State Management):

Storybook:

How to structure a storybook

Database

Cronjobs

Tasks that should run repeatedly can be defined in the backend. For further information see backend cronjobs.

Hierarchy

This document explains the hierarchy of the plants table. Please make sure that you already read the biology section of the glossary.

Introduction

The plants table contains entries of:

concrete plants, or
abstract plants (representants of ranks)

Concrete plants can be:

dragged and dropped to the map and
used as seed entry.

Abstract plants can be:

used to inherit attributes.

A concrete plant can be of following rank:

on species level, or
on variety level, or
on cultivar level.

Furthermore following must be true:

genus is below a family,
specie is below a genus,
a variety is below a specie,
a cultivar is below to a specie or a variety

The diagram below shows the hierarchy of entities with height and width as an example of attribute classification.

classDiagram

  class Family:::abstract {
    +int height
    +int width
  }
  class Genus:::abstract {
    +int height
    +int width
  }
  class Species {
    +int height
    +int width
  }
  class Variety {
    +int height
    +int width
  }
  class Cultivar {
    +int height
    +int width
  }

  Variety <|-- Cultivar
  Species <|-- Cultivar
  Species <|-- Variety
  Genus <|-- Species
  Family <|-- Genus

Each of these entities can have their own attributes. E.g., a variety below a specie can have different height than the specie itself.

Unique Name

In the database we have a column unique_name. The unique name are, either for abstract plants:

single latin word to specify "family", which always ends on: -aceae
single latin word to specify "genus"

Or is built up by several words (for concrete plants):

single latin word to specify "genus"
single latin word to specify "specie"
optional single latin word to specify "variety"
optional several words in single quotes to specify "cultivar", which starts with a capital letter

E.g. Brassica oleracea italica 'Ramoso calabrese'

Hybrid Names

Hybrid names are built up differently. Either two parent binomials, separated by a "x" or "×" or a given binomial, with or without an intercalated "×" (see Wikipedia). So the name does not necessarily say if a plant is a hybrid.

There is no special handling of hybrid names necessary, as the hybrid name is stored as unique name in the database.

Displaying the Unique Name

The unique name of a plant should be displayed as follows:

Latin name should be displayed in italics.
The cultivar name should be in regular font, enclosed in single quotes (as stored in the database).

For example: Brassica oleracea italica 'Ramoso calabrese'

The unique name alone usually is not displayed.

Displaying the Complete Name

The complete name of a plant should be displayed as follows:

If there is a common name, the common name appears first and should start with a capital letter (e.g., "tomato" becomes "Tomato").
If it is a plant name from the seed database, the name continues with hyphen - and the additional name.
This is followed by the unique name in brackets, unique name as described above in Unique Name.

The general format is:

Common name - additional name (unique name)

In cases where the common name is not available in the current language, it should be displayed as:

unique name - additional name

The cultivar is a part of the unique name.

For example (assuming Brassica oleracea italica doesn't have a common name):

Italian broccoli - violett (Brassica oleracea italica 'Ramoso calabrese')
Italian broccoli - violett (Brassica oleracea italica)
Italian broccoli (Brassica oleracea italica)
Brassica oleracea italica 'Ramoso calabrese' - violett
Brassica oleracea italica 'Ramoso calabrese'
Brassica oleracea italica - violett
Brassica oleracea italica

Displaying the Short Name

The short name should be displayed as follows:

Common name or, if common name is not not available, the unique name as described above in Unique Name.
If additional name is available, - and the additional name should be appended.

For example (assuming Abies mariesii and Brassica oleracea italica don't have common names):

Tomato - Gelbe Birne
Abies mariesii
Brassica oleracea italica 'Ramoso calabrese' - violett

Usage of Plant Names

The short name is for overview, e.g. when you see all labels in the map editor at once (plant labels).
The complete name should always be given if the user wants to know precisely which plant she is dealing with, e.g.:
- when the mouse is hovering over a plant in the plant layer,
- in search results or
- in plant details (left bottom toolbar).
The additional name must always be added if a plant is connected with a seed.

Rules

We know about names (abstract and concrete, including hybrid):

If it contains more than one word, it is a concrete plant.
If it contains only one word, it is an abstract plant (family or genus).
All entries with 2 words are a specie (de: Art),
All entries with 3 or more words are either:
- variety (de: Varietät) if all is spelled italic, or
- are cultivar (de: Sorte) if last part of the name (can be more than 1 word!) is not latin, not italic, is in 'single quotes'
All entries with a single x between the words are hybrid. We treat them like specie.

Attributes

Columns are documented in their respective structs.

We prefer strongly-typed data, e.g.:

enums
array of enums
numbers

Columns that contain text should be postfixed with:

_en for English text
_de for German text

As we often copy data from other sources, we maintain following columns for external references:

external_source: an array from enum where the first entry is the "main source" the other columns refer to:
external_id: an identifier of that source
external_url: the URL from where the data was taken

Plants are additionally classified as:

is_concrete_plant (is a concrete plant as opposite to an abstract plant)
is_tree (as search help within the tree layer)

from Permapeople

Following columns are removed:

environment (and its references)
type and is_variety, as variety is now determined from the name (rank to be calculated from name, see above)
wildflower
plants_of_the_world_online_name_synonym (redundant to link)
dutch_name, danish_name, french_name
when_to_harvest
propagation_cuttings
alternate_scientific_name
hortipedia
invasive_in
years_to_bear
useful_tropical_plants
thinning
light_tolerance
chill_hours, beef_tomato, invasive
folder_name (at least in DB)
native_climate_zones
adapted_climate_zones
propagation_direct_sowing

from Reinsaat

Unique name:

use Scientific name subheading together with name (as cultivar, see above) for our unique_name (Cucurbita ssp. from Scientific name kulturhinweise shouldn't exist)
Remove all occurrences of L., MIll., and var..
Entries on Reinsaat that are spelled like "Brassica oleracea convar. botrytis var. italica" https://www.reinsaat.at/shop/EN/brassica/broccoli/limba/ exist in our database as "Brassica oleracea italica". Add the Reinsaat entry to our database in a different row with the following nomenclature: Brassica oleracea italica 'Limba', with Brassica oleracea italica as parent, by following rules:
- Remove the term "convar." and its following word.
- Remove the "ssp." and its following word.
The name maps to cultivar (de: Sorte), i.e. a rank below variety and is expressed in non-latin words, such as 'Limba'. In our database we want them:
- back together in one name (the unique name, as described above) e.g. Brassica oleracea italica 'Limba' or Malus domestica 'Gala'.
- with a link to the variety, if present, otherwise species

Individual problems:

Daucus carota L. ssp. sativus --> Daucus carota sativus
Petroselinum crispum ssp. tuberosum --> Petroselinum crispum tuberosum
Papaver somnif. var. paeonifl. --> Papaver somniferum paeoniflorum
Alcea rosea fl. pl. --> Alcea rosea flore pleno
Campanula lat. macr. --> Campanula latifolia macrantha
Malva sylvestris ssp. maur. --> Malva sylvestris mauritiana
Sonnenblume, Velvet Queen: None should be Helianthus annuus

Schemata

Postgres supports enums so it is easy to define a static set of values. Right now, Mermaid doesn't support white spaces in names, so a _ character denotes white spaces in enums.

ER diagram

Not all columns are included in the ER diagram. For a complete documentation of all columns, see table descriptions.

erDiagram

seeds {
  INT id PK
  INT plant_id FK "NOT NULL"
  TEXT name "NOT NULL"
  TEXT variety
  INT created_by "NOT NULL"
}

plants {
  INT id PK
  TEXT unique_name "NOT NULL"
  TEXT[] common_name_en
  TEXT[] common_name_de
  TEXT family
}

spatial_relations {
  INT plant1 PK
  INT plant2 PK
  SPATIAL_RELATION_TYPE relation "NOT NULL"
}

temporal_relation {
  INT plant_earlier PK
  INT plant_later PK
  INT min_duration
  INT max_duration
  TEMPORAL_RELATION_EFFECT effect
}

maps {
  INT id PK
  TEXT name "NOT NULL"
  UUID created_by "NOT NULL"
  GEOMETRY geometry "NOT NULL"
}

layers {
  UUID id PK
  INT map_id FK "NOT NULL"
  LAYER_TYPE type "NOT NULL"
  TEXT name "NOT NULL"
}


plantings {
    UUID id PK
    UUID layer_id FK "NOT NULL"
    INT plant_id FK "NOT NULL"
    INT x "NOT NULL"
    INT y "NOT NULL"
}

drawings {
    UUID id PK
    UUID layer_id FK "NOT NULL"
    DRAWING_SHAPE_TYPE shape_type "NOT NULL"
    INT x "NOT NULL"
    INT y "NOT NULL"
}


users {
  UUID id PK
  TEXT country "NOT NULL"
  EXPERIENCE experience
  MEMBERSHIP membership
}

guided_tours {
  UUID user_id PK
  BOOLEAN editor_tour_completed "NOT NULL"
}

blossoms {
  TEXT title PK
  TEXT description
}


gained_blossoms {
  UUID user_id PK
  TEXT blossom FK "NOT NULL"
}

base_layer_images {
  UUID id PK
  UUID layer_id FK "NOT NULL"
  TEXT path "NOT NULL"
}


plants ||--o{ seeds : ""
relations }o--|| plants : "plant1"
relations }o--|| plants : "plant2"
layers }|--|| maps : "belongs to"
plantings }o--|| layers : "planted on"
drawings }o--|| layers : "drawn on"
plantings }o--|| plants : ""
maps }o--|| users : "created by"
blossoms ||--o{ gained_blossoms : ""
gained_blossoms }o--|| users : "gained by"
users ||--o| guided_tours : "completed by"
base_layer_images }o--|| layers : "belongs to"
users ||--o{ seeds : ""
plantings }o--|| seeds : ""

Plants Table

For performance reasons, we decided to disable some unused columns in the plants table for now.

For more information, see: PR #644

The following columns are commented out for now:

genus: text
medicinal_uses: text
material_uses_and_functions: text
botanic: text
material_uses: text
soil_water_retention: soil_water_retention[]
environmental_tolerances: text[]
native_geographical_range: text
native_environment: text
flower_colour: text
flower_type: flower_type
plant_references: text[]
is_tree: boolean
nutrition_demand: nutrition_demand
article_last_modified_at: timestamp without time zone
diseases: text
germination_temperature: text
introduced_into: text
habitus: text
medicinal_parts: text
native_to: text
plants_for_a_future: text
plants_of_the_world_online_link: text
plants_of_the_world_online_link_synonym: text
pollination: text
propagation_transplanting_en: text
resistance: text
root_type: text
seed_planting_depth_en: text
seed_viability: text
slug: text
utility: text
when_to_plant_cuttings_en: text
when_to_plant_division_en: text
when_to_plant_transplant_en: text
when_to_sow_indoors_en: text
sowing_outdoors_en: text
when_to_start_indoors_weeks: text
when_to_start_outdoors_weeks: text
cold_stratification_temperature: text
cold_stratification_time: text
days_to_harvest: text
habitat: text
spacing_en: text
wikipedia_url: text
days_to_maturity: text
pests: text
germination_time: text
description: text
parent_id: text
external_id: text
external_url: text
root_depth: text
external_article_number: text
external_portion_content: text
sowing_outdoors_de: text
spacing_de: text
required_quantity_of_seeds_de: text
required_quantity_of_seeds_en: text
seed_planting_depth_de: text
seed_weight_1000_de: text
seed_weight_1000_en: text
machine_cultivation_possible: boolean
edible_uses_de: text

Enum Types

These are all the enum types we currently have implemented:

erDiagram

enum_deciduous_or_evergreen{
    ENUM deciduous
    ENUM evergreen
}
enum_experience{
    ENUM beginner
    ENUM advanced
    ENUM expert
}
enum_external_source{
    ENUM practicalplants
    ENUM permapeople
    ENUM reinsaat
}

erDiagram

enum_fertility{
    ENUM self_fertile
    ENUM self_sterile
}
enum_growth_rate{
    ENUM slow
    ENUM moderate
    ENUM vigorous
}
enum_herbaceous_or_woody{
    ENUM herbaceous
    ENUM woody
}

erDiagram

enum_layer_type{
    ENUM base
    ENUM soil
    ENUM todo
    ENUM label
    ENUM paths
    ENUM photo
    ENUM shade
    ENUM trees
    ENUM winds
    ENUM zones
    ENUM plants
    ENUM drawing
    ENUM terrain
    ENUM habitats
    ENUM warnings
    ENUM watering
    ENUM landscape
    ENUM hydrology
    ENUM fertilization
    ENUM infrastructure
}
enum_life_cycle{
    ENUM annual
    ENUM biennial
    ENUM perennial
}
enum_light_requirement{
    ENUM full_sun
    ENUM partial_sun_or_shade
    ENUM full_shade
}

erDiagram

enum_membership{
    ENUM supporting
    ENUM regular
    ENUM contributing
}
enum_nutrition_demand{
    ENUM light_feeder
    ENUM moderate_feeder
    ENUM heavy_feeder
}

erDiagram

enum_drawing_shape_type{
    ENUM rectangle
    ENUM ellipse
    ENUM free_line
    ENUM bezier_polygon
    ENUM label_text
    ENUM image
}

enum_privacy_option{
    ENUM private
    ENUM protected
    ENUM public
}

enum_propagation_method{
    ENUM seed_direct_sow
    ENUM seed_transplant
    ENUM division
    ENUM cuttings
    ENUM layering
    ENUM spores
    ENUM seed
}

erDiagram

enum_quality{
    ENUM organic
    ENUM not_organic
    ENUM unknown
}
enum_quantity{
    ENUM nothing
    ENUM not_enough
    ENUM enough
    ENUM more_than_enough
}
enum_spatial_relation_type{
    ENUM companion
    ENUM neutral
    ENUM antagonist
}
enum_temporal_relation_effect{
    ENUM positive
    ENUM negative
}

erDiagram

enum_salutation{
    ENUM ms
    ENUM mrs
    ENUM mr
    ENUM mx
}
enum_shade{
    ENUM no_shade
    ENUM light_shade
    ENUM partial_shade
    ENUM permanent_shade
    ENUM permanent_deep_shade
}
enum_soil_ph{
    ENUM very_acid
    ENUM acid
    ENUM neutral
    ENUM alkaline
    ENUM very_alkaline
}

erDiagram

enum_soil_texture{
    ENUM sandy
    ENUM loamy
    ENUM clay
    ENUM heavy_clay
}
enum_track{
    ENUM beginner
    ENUM seasonal
    ENUM completionist
    ENUM expert
}
enum_water_requirement{
    ENUM dry
    ENUM moist
    ENUM wet
    ENUM water
}

These are all the enum types we currently have NOT implemented:

erDiagram

enum_tag{
    ENUM Leaf_crops
    ENUM Fruit_crops
    ENUM Root_crops
    ENUM Flowering_crops
    ENUM Herbs
    ENUM Other
}

Table descriptions

`Plants`

*Column name*	*Data type*	*Example*	*Additional information*
id	integer	355	PRIMARY KEY
unique_name	text	Allium schoenoprasum	NOT NULL
common_name_en	text[]	{chives}
common_name_de	text[]	{schnittlauch}
family	text	Alliaceae
edible_uses_en	text	NULL
functions	text	NULL
heat_zone	smallint	NULL
shade	shade	light shade
soil_ph	soil_ph[]	{acid}
soil_texture	soil_texture[]	{sandy,loamy,clay}
ecosystem_niche	text	NULL
deciduous_or_evergreen	deciduous_or_evergreen	NULL
herbaceous_or_woody	herbaceous_or_woody	herbaceous
life_cycle	life_cycle[]	{perennial}
growth_rate	growth_rate[]	{moderate}
height	integer	30
fertility	fertility[]	{"self fertile"}
created_at	timestamp without time zone	2024-05-31 12:03:49.820927	NOT NULL, defaults to current time
updated_at	timestamp without time zone	2024-05-31 12:03:49.820927	NOT NULL, defaults to current time
has_drought_tolerance	boolean	false
tolerates_wind	boolean	NULL
preferable_permaculture_zone	smallint	NULL	-1..6 (-1 should be printed as 00)
hardiness_zone	text	[3,12)
light_requirement	light_requirement[]	{"full sun","partial sun/shade"}
water_requirement	water_requirement[]	{moist}
propagation_method	propagation_method[]	{"seed - direct sow","seed - transplant",division}
alternate_name	text	Wild chives, Flowering onion
edible	boolean	true
edible_parts	text[]	{bulb,flowers,leaves,root}
spread	integer	30
warning	text	NULL
version	smallint	24
external_source	external_source	permapeople
sowing_outdoors	smallint[]	NULL
harvest_time	smallint[]	NULL
seed_weight_1000	double precision	NULL

`Spatial Relations`

Store relations between plants.

*Column name*	*Data type*	*Example*	*Additional information*
plant1	integer	355	PRIMARY KEY, FOREIGN KEY to `plants.id`, id of first plant
plant2	integer	1920	PRIMARY KEY, FOREIGN KEY to `plants.id`, id of second plant
relation	relation_type	companion	NOT NULL, type of relation
note	text	Imported via scraper	comment about the relation

`Temporal Relation`

Store possible temporal relations between plants, which make up the crop rotation.

*Column name*	*Data type*	*Example*	*Additional information*
plant_earlier	integer	355	PRIMARY KEY, FOREIGN KEY to `plants.id`, id of earlier plant
plant_later	integer	1920	PRIMARY KEY, FOREIGN KEY to `plants.id`, id of later plant
min_duration	integer	6	the absolute minimum duration of the effect in months (min. 6)
max_duration	integer	12	the absolute maximum duration of the effect in months
effect	temporal_relation_effect	positive	`positive` or `negative` effect between two plants

`Maps`

*Column name*	*Data type*	*Example*	*Additional information*
id	integer	1	PRIMARY KEY
name	text	My Map	NOT NULL, only alphanumerical values
deletion_date	date	2024-04-04
last_visit	date	2023-04-04
is_inactive	boolean	false	NOT NULL
zoom_factor	smallint	100	NOT NULL, value used in formula "X by X cm", e.g. 100 would mean "100 x 100 cm", range from 10 to 100000
honors	smallint	0	NOT NULL, 0 to infinity
visits	smallint	0	NOT NULL, 0 to infinity
harvested	smallint	0	NOT NULL, 0 to infinity, amount of plants harvested on this map
privacy	privacy_option	protected	NOT NULL
description	text	Our first map
location	geography	NULL	PostGIS Geodata, location of the map
geometry	geometry	0103000020E61000000100...	NOT NULL, boundaries of the map
created_by	uuid	affb3987-0d75-42b8-b34a-cf7eec4e151b	NOT NULL, is also the map owner
creation_at	timestamp	2023-04-04 10:11:12	NOT NULL, defaults to current time
modified_by	uuid	affb3987-0d75-42b8-b34a-cf7eec4e151b	NOT NULL
modified_at	timestamp	2023-04-04 10:11:12	NOT NULL, defaults to current time

`Seeds`

*Column name*	*Data type*	*Example*	*Additional information*
id	integer	1	PRIMARY KEY
name	text	Some tomato seeds	NOT NULL, at least 1 alphanumeric character, no dashes
harvest_year	smallint	2018	NOT NULL
use_by	date	2028
origin	text	Vienna, Austria
taste	text	Sweet
yield	text	high
quantity	quantity	more than enough	NOT NULL
quality	quality	Organic
price	smallint	10.99
generation	smallint	7
notes	text	NULL
plant_id	integer	5557	NOT NULL, FOREIGN KEY to `plants.id`
created_by	uuid	affb3987-0d75-42b8-b34a-cf7eec4e151b	NOT NULL
archived_at	timestamp	NULL

`Layers`

*Column name*	*Data type*	*Example*	*Additional information*
id	uuid	9b77d9b1-02c3-4fac-97bf-686b9f4ea38d	PRIMARY KEY
map_id	integer	1	NOT NULL, FOREIGN KEY to `maps.id`
type	layer_type	plants	NOT NULL
name	text	Plants Layer	NOT NULL
is_alternative	boolean	false	NOT NULL, true if the layer is an user-created alternative layer
mark_deleted	timestamp	NULL
order_index	integer	1	NOT NULL

`Plantings`

A single plant or an area of plants that has been placed on a map.

*Column name*	*Data type*	*Example*	*Additional information*
id	uuid	440d518c-dc50-4ff3-9943-9f578a1b7e7d	PRIMARY KEY
plant_id	integer	355	NOT NULL, FOREIGN KEY to `plants.id`
is_area	boolean	false	NOT NULL, true if the planting is an area of plants instead of a single plant
x	integer	714	NOT NULL, x coordinate on map
y	integer	538	NOT NULL, y coordinate on map
size_x	integer	30	NOT NULL, size on x-axis on map
size_y	integer	30	NOT NULL, size on y-axis on map
rotation	real	0	NOT NULL, rotation on map
add_date	date	2024-03-01	Date when the plant was planted
remove_date	date	NULL	Date when the plant was removed
seed_id	integer	NULL	FOREIGN KEY to `seeds.id`
notes	text	NULL	NOT NULL
created_at	timestamp	2024-01-01 10:11:12	NOT NULL, defaults to current time
modified_at	timestamp	2024-01-01 10:11:12	NOT NULL, defaults to current time
created_by	uuid	affb3987-0d75-42b8-b34a-cf7eec4e151b	NOT NULL
modified_by	uuid	affb3987-0d75-42b8-b34a-cf7eec4e151b	NOT NULL
layer_id	uuid	b8e3ea1c-5432-459b-a9c9-736a29ea60f0	NOT NULL, FOREIGN KEY to `layer.id`

`Users`

*Column name*	*Data type*	*Example*	*Additional information*
id	uuid	00000000-0000-0000-0000-000000000000	NOT NULL, PRIMARY KEY, the UUID from Keycloak
salutation	salutation	Mr	NOT NULL
title	text	NULL
country	text	Austria	NOT NULL
phone	text	NULL
website	text	NULL
organization	text	NULL
experience	experience	beginner
membership	membership	contributing
member_years	integer[]	{2023}	years of active membership
member_since	date	2023-07-12
permacoins	integer[]	{0}	array of positive integers

`Guided Tours`

*Column name*	*Data type*	*Example*	*Additional information*
user	uuid	00000000-0000-0000-0000-000000000000	PRIMARY KEY
editor_tour_completed	boolean	false	has the user completed the Map Editor Tour

`Blossoms`

*Column name*	*Data type*	*Example*	*Additional information*
title	text	Novice Gardener	PRIMARY KEY
description	text	Plant your first plant
track	track	Beginners Track	the track (category) this blossom belongs to
icon	text	NULL
is_seasonal	boolean	false	NOT NULL, if blossom resets and repeats every year

`Gained Blossoms`

*Column name*	*Data type*	*Example*	*Additional information*
user_id	uuid	00000000-0000-0000-0000-000000000000	PRIMARY KEY
blossom	text	1	PRIMARY KEY
times_gained	integer	1	NOT NULL, 0 to infinity
gained_date	date	2023-04-10	NOT NULL

`Base Layer Images`

*Column name*	*Data type*	*Example*	*Additional information*
id	uuid	ae245486-fe22-4e59-aed8-d5981d245d1c	PRIMARY KEY
path	text	/Photos/Vineyard.jpg	NOT NULL
rotation	real	0	NOT NULL
scale	real	100	NOT NULL
layer_id	uuid	e09a5af0-2f84-4cef-ae75-8bcc66862be3	NOT NULL, FOREIGN KEY to `layers.id`

`Drawings`

*Column name*	*Data type*	*Example*	*Additional information*
id	uuid	ae245486-fe22-4e59-aed8-d5981d245d1c	PRIMARY KEY
shape_type	drawing_shape_type	rectangle	NOT NULL
add_date	date	2024-04-04
remove_date	date	NULL
rotation	real	0	NOT NULL
scale_x	real	1	NOT NULL
scale_y	real	1	NOT NULL
x	integer	460	NOT NULL
y	integer	645	NOT NULL
properties	jsonb	{"color": "#000000", "width": 275.0, "height": 233.0, "fillPattern": "none", "strokeWidth": 3.0}	NOT NULL
layer_id	uuid	9b77d9b1-02c3-4fac-97bf-686b9f4ea38d	NOT NULL, FOREIGN KEY to `layers.id`

Decision Process

Problem

Simply discussing in an issue and then implementing a solution is okay for non-substantial changes. Substantial decisions, however, must be made in a transparent and participative way.

Discussing fundamental problems in forum-like threads showed to be repetitive and ineffective.
Decisions by supervisors are undemocratic.
Decisions in meetings are nontransparent for the outside world.

Main Purpose

The main purpose of decisions is

to have clear descriptions of technical problems and solutions.
to get a common understanding of the problems and the impacts of possible solutions.

Constraints

All relevant information about decisions must be within PermaplanT's repository.
@markus2330 need to approve the decision.

Assumptions

People want to be informed about or even participate in what PermaplanT looks like in the future.
Decision authors have some scientific background and want decisions based on science, and not only on opinions.
If assumptions, including this ones written here, are broken, decisions will be redone.
Decision authors focus on getting the best solutions and not to wish for the impossible. They have strong motives to also complete the decision.
The decision process itself isn't a barrier for people to write their first decision.

Solutions

Create a decision process tailored to PermaplanT
Issues (often do not result to a PR that documented the outcome)
GitHub discussions (-||-)
PEPs: https://peps.python.org (tailored for programming language specifications, not ideal for architectural decisions)
Rust RFCs: https://www.ietf.org/standards/rfcs/ (-||-, see also https://forge.rust-lang.org/compiler/mcp.html)
Change requests: https://en.wikipedia.org/wiki/Change_request

Decision

We use a decision process tailored to PermaplanT, in which decisions need to:

be implementable within the project/term
be according to PermaplanT's goals

We use the template TEMPLATE.md. Explanations of the template are in EXPLANATIONS.md.

Decision authors are the main force to improve the text to get a decision forward.

Rationale

The process is lightweight and simple.
The template makes sure important points are not forgotten.
Every decision is by design in its own file with its own Git history.
PRs allow to better support the constraint that everything must be within PermaplanT's repository.
Several "Related Decisions" are very important even if everyone agrees on one solution. They allow reviewers and future readers of the decision to understand which options were considered and why they were rejected.
The decision process is focused around the decision text (and not forum-like discussions), so that:
- The resulting text is understandable without reading any discussions.
- There is a common understanding after only reading the decision text.
- To avoid any gaps of reading discussions and the decision.

Implications

Decisions encourage to write documentation before actually writing code.

This is the only non-technical decision, so no issues are related.

Notes

Even though they use the decision template, following decisions are not decisions:
- Template: copy this to start a new decision
- Explanations: read this
The first idea often is not the best, don't fixate on it. Abraham Luchins called this the “Einstellung effect.” Thus we encourage to generate as many ideas as possible for any problem (interrupt effect).
We have a tendency to add: Take courage to also propose solutions that (mostly) remove code. See Leidy Klotz et al., e.g. “People systematically overlook subtractive changes“.
Failures are not a bad thing. It is a good thing to have "rejected" decisions for future references and to recheck if assumptions change.
Decisions are about "Why?" and not about "Who?" or "When?". Such discussions should be in the project or meetings.
Discussions in issues/discussions are not prohibited. To not waste time, it is recommended, however, to start with the decision as described here asap.

Written by Markus Raab @markus2330

EXPLANATIONS

We base our decision process and template on:

This document describes every section of our TEMPLATE.md.

Problem

Clearly define:

the context in which the problem exists
your observation of the problem
ideally an example for that problem

Constraints

List all constraints given by:

use cases
requirements
goals
guidelines
standards
other decisions
the scope (i.e. describe what shouldn't change)

Note: The decision (but not necessarily the solutions) must fulfill all constraints.

Assumptions

Assumptions are often overlooked, so this section needs special care and honesty. Assumptions are what we believe to be true but do not or cannot really know, e.g.:

what users will accept
perceived usability
if the implementation will be faster/slower
estimations of costs
problems/risks that might turn up

Note: The decision (but not necessarily the solutions) must not break any assumptions.

Solutions

This is a list of all solutions and a rationale why not-chosen solutions were not taken, e.g. because:

the solution does not solve the whole problem
some constraints or assumptions are violated
another solution:
- solves the problem better
- is more in line with PermaplanT's architecture
- better supports PermaplanT's goals
- better fulfills non-functional requirements

Decision

Here should be a detailed description of the best solution, i.e., the decision. It should make clear how the implementation should be done.

Referring back to the solutions written above is allowed.

Rationale

Give all details why the solution:

solves the problem best
is best in line with our goals
fulfills all constraints and assumptions

Also describe all drawbacks the solution has.

Implications

Here is a full description of everything that the decision will change or whatever needs to be changed because of the decision. This can be:

effect on other decisions, goals, etc.
non-obvious implementation tasks, e.g. changing in different needs to be implemented
which issues get solved
which documentation needs to be updated
which concepts change
which guarantees are added/removed

This section has links to other decisions with description what the relation is. One-side relations are allowed, not every decision must link back. Decisions that give constraints must be listed in "Constraints" above.

Note: Sometimes the best solution is only understood if the relation between decisions becomes clear. Make sure that everything that requires updates to a decision, is listed as "Constraints" or "Assumptions".

Notes

Here is a full list of off-line discussions, issue trackers, PRs etc. related to this decision. Preferable it is linked, but if it is not possible, it can also be in full-text here. If particular information is important and not present in any sections above, please quote it here.

Any incomplete and unexplored idea/opinion, which is not complete enough to be in "Solutions", can be written here. For example, if it is obvious that the idea does not even solve the problem. Unlike the main decision and solutions, text in the notes does not need rationale.

Furthermore, the author, acknowledgments, dates etc. can be written here.

TEMPLATE

Problem

Constraints

Assumptions

Solutions

Alternative A

Alternative B

Alternative C

Decision

Rationale

Implications

Notes

Authentication & Authorization

Problem

The user wants to log in once and be able to fetch resources from the Nextcloud instance as well as from PermaplanT database. The users need to authenticate themself (who is the user). Then they get the appropriate authorization (does the user have the right privileges) to perform the action.

OAuth2.0: User can authorize client to fetch resources from resource server.

OpenID Connect: Extension of OAuth2.0 for authentication

Constraints

single account to access PermaplanT and Nextcloud
we don't implement our own auth solution

Assumptions

Nextcloud and PermaplanT backend are the only services we provide
we don't need roles/scopes (everyone can access all parts of the API)
access control is quite simple, e.g., which users can read or write on which map

Solutions

Nextcloud-only

OpenID Connect authentication & authorization flow with:

Authorization server: Nextcloud OIDC App

Resource server 1: Nextcloud OAuth2

Resource server 2: PermaplanT backend

Client: PermaplanT frontend

Notes:

Currently it is not yet possible to use an issued Access Token or ID Token to access resources at the Nextcloud instance it self.

- H2CK/oidc

This is a major problem with this approach.

Nextcloud OAuth2 implementation currently does not support scoped access. This means that every token has full access to the complete account including read and write permission to the stored files. It is essential to store the OAuth2 tokens in a safe way! Without scopes and restrictable access it is not recommended to use a Nextcloud instance as a user authentication service.

- Nextcloud documentation

App password login flow

This is the login flow described in the Nextcloud documentation. A client can retrieve an app password for a user. Opposed to token authentication described before the app password is permanent and should not be stored anywhere in the frontend. This approach requires PermaplanT to have its own authentication server and therefore separate accounts!

Separate identity provider

OpenID Connect authentication & authorization flow with:

Authorization server / Idenentity provider: PermaplanT

Resource server 1: Nextcloud

Resource server 2: PermaplanT

Client 1: Nextcloud WebClient with oidc login or user_oidc

Client 2: PermaplanT

Notes: In this approach the accounts are managed by PermaplanT, therefore requires implementing an identity provider in PermaplanT.

This approach was tested with Keycloak as identity provider and user_oidc(official oidc app) for oidc capabilities in Nextcloud and works as intended. The only limitation is that Nextcloud does not offer scoped access at the moment -> the authenticated app can access all of the resources the user has access to.

Identity providers

comparison of identity providers

Decision

We will use oidc with the separate identity provider Keycloak.

Keycloak itself will run as a separate service like Nextcloud. Users are created there instead of in Nextcloud/PermaplanT and users can then log in via Keycloak.

So in the PermaplanT frontend the user will be redirected to Keycloak. They can login in Keycloak and then they get redirected back to PermaplanT. From then on all requests are authorized via JWT. How that happens in detail is specified by the OAuth2 spec and there are also multiple ways of doing that. We will use the recommended variant which is Authorization Code Flow with PKCE. The backend will then simply validate the tokens and extract roles/user information out of them. This will be done by either by a library or implemented by us as this part is not that complicated.

Keycloak itself can either run as an executable or as a container. Apart from that it only requires a database so we can use our existing PostgreSQL for that.

Rationale

OpenID Connect is an interoperable authentication protocol based on the OAuth 2.0 family of specifications. It uses straightforward REST/JSON message flows with a design goal of “making simple things simple and complicated things possible”. It’s uniquely easy for developers to integrate, compared to any preceding Identity protocol. -- openid.net

Keycloak is a FLOSS solution for identity and access management which is one the most popular self hosted solutions. Some of the PermaplanT team members have already experience with it.

Further Notes

There was an attempt to implement OIDC in nextcloud/server but the issue lost traction and was finally not merged because of missing integration tests (https://github.com/nextcloud/server/pull/12567)

Backend API documentation

Problem

We need a way to document the API in the backend.
Otherwise we would have to read the Rust Code every time we want to develop a new part of the frontend.

Constraints

It must be easy enough to use as most people know only a little bit of Rust.
It should take less time compared to manually maintaining API documentation.

Assumptions

The backend's API is only used by the frontend.
The API documentation is not used while a new endpoint is being created as there will be a lot of breaking changes during that time.
The API documentation is used by developers wanting a nice easily accessible overview of all APIs.
The API documentation is not fixed, it might change as the code evolves.

Solutions

Utoipa

You can think of Utoipa as the Rust equivalent to Swagger/OpenApi in Java.

It is a Rust crate which allows you to annotate your code (structs and endpoints) and automatically generate OpenApi documentation from that.
You can also generate a UI endpoint just like with Java Spring.

Compared to Swagger in Java there is a bit more you have to configure to get it running.

Once you get it running you get endpoints with schemas and examples representing the API.
You can also execute example requests directly from the UI to see how the backend behaves.

API Blueprint

Information from https://testfully.io/blog/api-blueprint/.

Before starting on a new endpoint we would write a markdown document specifying in detail what the endpoint should return and in what format.
There is also a lot of tooling for API Blueprint.

Decision

We will use Utoipa to automatically generate API documentation from code.
Additionally we will provide an endpoint which will display the API documentation using Swagger.

Rationale

With Utoipa it is possible to generate API documentation directly from code whereas with API Blueprint we would have to write the API documentation by hand in markdown files (at least I have yet to find a crate that automatically generates required markdown files).
Additionally if we where to use API Blueprint every time the API changes we would have to remember to change the markdown files as well, which is easily forgotten and might become tedious when making smaller changes.

For me (@kitzbergerg) it is easier to use Utoipa as it generates Swagger/OpenApi which I have already used.
I would have to learn API Blueprint and its tooling from scratch.
With that I would argue that more people know Swagger/OpenApi leading to easier onboarding.

One advantage of API Blueprint would be that we have to carefully think about the API (API-First Approach) before actually implementing.
This leads to a clean API in the long run, however it is more difficult to quickly prototype and try different approaches (which in my opinion is currently more important as we are somewhat at the beginning of the project).

Implications

When deciding on a new endpoint it will take longer for the API documentation to be done, as:
- the Rust structs must be implemented
- #[derive(ToSchema)] must be present for all of those structs, and
- you also might need to change the API config.
The API documentation will not deviate from the actual implementation as it is generated from code.
Developers have to know Swagger, but once they do they can easily check the API in the browser served by the backend.
Backend Developers have to invest some time into reading Utoipa's documentation.
If you have some understanding of Rust it shouldn't take longer than 1h to use Utoipa when creating a new endpoint for the first time (that includes reading the documentation quite thoroughly).

Notes

Mail Client for the Backend

Problem

We want to be able to send mails from the backend.

The typical communication when sending a mail is as follows:

Your email client communicates with your SMTP server.
Your SMTP server communicates with the recipient's domain's DNS server to find the address of their SMTP server.
Your SMTP server communicates with the recipient's SMTP server.
The recipient's SMTP server delivers the email to the recipient's mailbox.

Example use case

A user enters a question into the contact form on the frontend.
The frontend should now send a request to the backend.
The backend then send a mail to somebody who can answer this question.

Constraints

Currently there doesn't seem to exist a crate to send emails without requiring a mail-server. We should therefore also use username and password as credentials in the backend.

Solutions

lettre

lettre is one of the biggest (if not the biggest) mail clients in Rust.

The crate can be used to send emails. For that it requires a mail-server it can connect to and send mails from.

mail_smtp

mail_smtp can also be used to send emails (and also requires a mail-server).

Decision

We should use the crate lettre for sending mails.

Rationale

lettre is as of writing this the most widely used crate I have found with 1,343,736 total downloads.
The usage also seems easier than with other mail clients.

mail_smtp has only 3,457 downloads which can't compare to lettre.

Implications

We have to create a user in our mail-server lettre can use to send emails.
Our mail-server's configuration has to be provided to the backend (URI, username, password, ...)

Backend ORM/SQL Crate

Problem

We are currently using Diesel as our ORM in Rust.

Since Diesel doesn't support async out of the box we will look at other alternatives and see if a switch is reasonable.
The reason why I believe pure async is better in our case is that it quite difficult (especially for Rust beginners) to mix async and blocking code.

There might also be advantages of other ORM crates that as of writing this have not been considered.

Constraints

Migrations need to be supported
PostGIS extension need to be supported

Assumptions

Diesel is a solid choice, therefore unless other ORMs have obvious advantages differences will not be looked at in detail.

Solutions

Diesel

Diesel currently is the most used ORM in the Rust ecosystem.
It supports migrations written in SQL that can be executed from command line.

Diesel is the ORM we are using as of writing this decisions.

Diesel with `diesel_async`

diesel_async is a drop-in replacement of corresponding diesel methods providing async support.

According to the author of diesel_async the project won't be officially released (meaning version 1.0) until Rust has better support for async.
As Rust version 1.67 has no async traits and the likes yet performance might be slightly worse than Diesels.
You can see the discussion about that on Reddit.

To switch from diesel to diesel_async we just would have to import different traits and make our functions async.
diesel_async doesn't provide support for async migrations. This however is not a problem as migrations are run at startup anyways and therefore has no impact.

SeaORM

SeaORM is based upon sqlx and supports async out of the box.
It supports migrations written in Rust.

In my opinion SeaORM provides better and more easily readable documentation out of the box. This might however just be my personal preference.

Decision

We use diesel_async with postgis-diesel.

Rationale

At the current state the small advantages sea-orm might have over Diesel don't justify switching as this would involve quite a big change. Furthermore, it seems to be slower and without support for PostGIS.

An interesting article to look at is https://www.sea-ql.org/SeaORM/docs/internal-design/diesel/.
Apart from minor differences Diesel and SeaORM provide similar functionality.

`async`

Both diesel_async and sea-orm provide async support.

This might not necessarily lead to a performance increase, but it is easier for (especially inexperienced) developers to stay in full async.

For example if you forget web::block when executing a query using Diesel you block the async executor (tokio in our case) until the query is finished.
We currently have a lint warning about async functions that do not use await, you will therefore notice this mistake.
However for inexperienced Rust developers it might be difficult to find out why this warning occurred as the code compiles and runs perfectly fine (especially with small loads).

This has already happened in our code.

Furthermore it is really difficult to spot blocking functions without actually knowing the whole codebase (and therefore knowing which functions are blocking).
As an example as of writing this every call to any of the functions in the service directory would block the executor.
In a PR it is almost impossible to spot something like this when you are not the one who actually wrote the function originally.

Performance

Metrics by Diesel

To sum up the above article:
According to this article Diesel performs the best on basically all metrics. Diesel_async brings a slight performance decrease.

PostGIS

There is postgis-diesel for Diesel, which works for diesel_async as well.
I have found nothing similar for SeaORM.

Backend Programming Language

Problem

When selecting a backend programming language, a major issue is the range of options available, each with its own strengths and capabilities. This makes it challenging to determine the best language for a particular project or application.

Constraints

The language and its ecosystem must be free software.
The language must be performant.
The code must be easily maintainable.
Scalability
Security
Availability of developers and support

Assumptions

Considered Alternatives

Kotlin
Python
JavaScript

Decision

We will use stable Rust version 1.67.1 (2023-02-09), installed by rustup, as the backend programming language for PermaplanT.

Rationale

Rust has a growing community of developers and a robust ecosystem of libraries and tools, which can make it easier to build and maintain backend applications. Overall, Rust's combination of performance, safety, and support make it a viable option for backend development.

Implications

Notes

Backend Testing Strategy

Problem

Our current setup regarding test in the backend isn't completely thought through.
There is no differentiation between unit and integration tests.
Setting up new tests seems more complicated than necessary.
It isn't clear how the test database/connection is actually setup up or how it works with begin_test_transaction().

Constraints

diesel and typeshare still have to work (even if we separate into binary and library part)

Assumptions

Solutions

Run all tests from the `src/` directory

This is the current solution.

All tests are put into the src/ directory and run from there.
There is no real separation between unit and integration tests as all tests are treated the same.

Split into tests in `src/` and `tests/`

This would involve splitting the backend into a binary and library part (see the rust book for reference).
The code change required for this would be rather small, mainly consisting of renaming the current main.rs into lib.rs and creating a new main.rs that calls into the library.

After this is done there would be a clear differentiation between unit and integration tests (according to the rust book definition of unit/integration tests).

Unit tests are in src/.
They are modules annotated with #[cfg(test)] and are supposed to test individual functions or smaller parts of the code (see here).
We might not even need to create unit tests as of now as there are no complicated functions.
Integration tests are in tests/.
They are separate from the other code and only have access to public facing API (in this case meaning public functions/structs/... that can be accessed from outside the library part; see here).
Using this we would start the server similarly to how main.rs starts the server and then make requests and validate responses.

A major advantage of this approach is that the server is actually started in a very similar way to how it would be started via cargo run.

On the other hand it might be more difficult to set up tests as you first have to start the server (in its own thread), wait until it is up and then send requests to it (probably with something like reqwest).

Decision

We should keep the tests only in src/. We should still do a bit of refactoring for the tests we currently have, although there won't be major changes.

Tests in src/test/ are from now on defined as backend integration tests.
Tests in other modules/files have to look like the following and are defined as unit tests:

#![allow(unused)]
fn main() {
struct Plants;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_plants() {
      // Test complicated plants function here
      todo!()
    }
}
}

Rationale

Our project is not a library therefore splitting it into binary and library part doesn't really make much sense.

Actix itself writes tests as unit tests (although they are in part called integration tests in their documentation). It just seems easier to define specific services and handlers that you want to test.

Most resources I found use integration tests exclusively for libraries. Application servers are tested without starting the whole server, but rather by calling individual endpoints (like in Actix' documentation).

Implications

Notes

Backend Web Framework

Problem

When looking for a web framework for Rust, one of the main challenges is that there are many different options to choose from, each with its own set of features and capabilities

Constraints

Assumptions

Considered Alternatives

Salvo (faster than Actix but no Diesel integration)
Xitca (unstable)
Axum (quite slow)
Rocket (quite slow)

Decision

We will use Actix Web as the backend web framework for the Permaplant app.

Rationale

Actix Web is a web framework for Rust that is known for its high performance, modular design, and extensibility. Some of the reasons why Actix Web is a good choice for a web project include its focus on scalability and reliability, its support for asynchronous programming, and its rich ecosystem of plugins and extensions:

Implications

Notes

CI/CD

Problem

We need to implement a continuous integration and delivery (CI/CD) process to automate the build, testing, and deployment of the app.

Constraints

The CI/CD process must be compatible with our version control system (Git).
The process must be able to run automated tests as part of the build process.

Assumptions

The app is well-structured and easy to test.

Considered Alternatives

GitHub Actions: GitHub Actions is a cloud-based service that is built into GitHub and is specifically designed for CI/CD with GitHub repositories. It is easy to use and requires little technical knowledge to set up. However, it may not be as flexible as some other alternatives, and it may not be suitable for projects that require more advanced CI/CD capabilities.

Decision

We will use Jenkins for our CI/CD process.

Rationale

While GitHub Actions is a convenient and easy-to-use option, it may not be as flexible as Jenkins, which has a wider range of features and plugins. In addition, Jenkins is an open-source tool that is widely used and has a large community of users and developers, which means that it is likely to be well-documented and supported. Finally, Jenkins is compatible with a wide range of tools and services, which may be important for the app as it grows and evolves.

Implications

Notes

Database

Problem

The challenges of choosing a database include finding a database that meets the specific needs and requirements of the application or project. PermaplanT will have several thousands of entries including plants.

Constraints

The database must support the app's needs for storing and querying plant information.
The database should be scalable and able to handle potential future increases in users and data.
The database should be well-supported and have a strong community.
The database should have extra types for geometry and raster.

Assumptions

Considered Alternatives

MySQL: MySQL is a popular and well-supported open-source database Both PostgreSQL and MySQL are relational databases however, PostgreSQL is more flexible when it comes to data types and allows for more advanced data types, such as arrays and JSON. This can be useful for applications like PermaplanT that may have more complex data structures.
MongoDB: MongoDB is a popular NoSQL database. The data for the app is likely to be structured and have relationships between different entities, such as field plants, trees, and landscapes. A relational database would be more suited.

Decision

We will use PostgreSQL as the database for the PermaplanT app in addition with a PostGIS extension for spatial queries. To use it in Rust we will use theORM engine Diesel with PostGIS Diesel.

Rationale

PostgreSQL is a well-supported and widely-used open-source database that is capable of handling the complex data structures and querying needs of the PermaplanT app. It is also scalable and has a strong community, making it a good choice for the app's database needs.

PostGIS is an open-source extension for PostgreSQL that enables the storage and manipulation of spatial data, such as points, lines, and polygons. It provides various functions and operators for performing spatial queries. As almost all entries in the database include their coordinates, PostGIS is a valuable tool for querying and working with spatial data.

Implications

The app will need to be configured to use PostgreSQL as its database.
Any queries or data access code in the app will need to be updated to use PostgreSQL-specific syntax and features.
The app will need to be tested with PostgreSQL to ensure compatibility and performance.

Notes

Database Plant Hierarchy

Problem

The challenge is to define the structure of the database in a way that the data:

can be easily queried so the most specific data according the taxonomy is retrieved and
updated without redundancy (e.g. setting attributes for a whole family).

Here we will discuss how the hierarchy should be defined in the database.

Constraints

The database structure should represent the simplified taxonomy we need for PermaplanT.
There must be a unique identifier for later updates of the database.

Assumptions

Performance of the database is efficient enough.
Subfamilies will not be introduced by PFAF/Permapeople.
A new plant added by us won't need subfamilies.
We don't need convar between species and variety.

Considered Alternatives

Inheritance feature of PSQL

Inheritance cannot solve the challenge. See the PSQL documentation as cited here:

Inheritance does not automatically propagate data from INSERT or COPY commands to other tables in the inheritance hierarchy.

All check constraints and not-null constraints on a parent table are automatically inherited by its children, unless explicitly specified otherwise with NO INHERIT clauses. Other types of constraints (unique, primary key, and foreign key constraints) are not inherited.

Table inheritance is typically established when the child table is created, using the INHERITS clause of the CREATE TABLE statement.

So the inheritance is useful to deal with complex DDL structure on the startup, but will not help us to avoid bulk operations e.g. updating a column for every variety in the entire genus

One table per taxonomy rank and one for concrete plants.

Example

Pros:

Schema is easy to understand.

Cons:

By splitting the taxonomy ranks into multiple tables we loose the ability to have simple foreign keys to these when defining plant relationships. There would be two approaches to alleviate this.

Manage multiple nullable foreign keys and make sure that exactly one of them is set. Would lead to complex validations for inserts and updates.
Generalize it to a self-managed compound foreign key with a table name and id. We would lose referential integrity here.

One table for taxonomy ranks and one for concrete plants.

Example

Pros:

Inserting new plants is easy.

Cons:

Attribute overrides can only be done on variety or cultivar level.
More complex insert and update logic. When a species/variety is added or updated the columns can't just be set. First we need to make sure all higher levels are in the table. Then we need to check for each column value if there is a higher rank that already defines the same value. Only if we can't find a match the value should be written.

All ranks in one table.

Example

Pros:

Flexible and extendable.
Allow attribute overrides on arbitrary level.

Cons:

Almost everything in the plants table needs to be nullable.
More complex insert and update logic.

Decision

We go with the last option "All ranks in one table" as described in our documentation.
We rename "binomial name" to "unique name" and guarantee that it is unique.
We add "cultivar" as lowest rank.
We remove the rank "subfamily".

For details on the schema see this example SQL Here are some example queries

Rationale

Having everything in one table makes maintenance of the database easier: Attributes of plants, and especially icons, can be defined on any rank level.

We need a unique name (across all entries) for updates. We call it unique name (and not scientific or Latin) because cultivar:

don't have a scientific name.
don't have a Latin name.

There are no attributes which need a rank higher than family, see:

https://www.youtube.com/watch?v=0hAhy30_6fc
https://www.try-db.org/TryWeb/Home.php
Lüttge, Kluge, Bauer (2005): Botanik. Wiley-vch Verlag.
Das große Buch der Biologie.

Subfamily gets removed because:

is currently not present in the database.
the traits specific to subfamilies are not very important to PermaplanT.
a new plant assigned to a subfamily can be assigned (manually) to the family as well.

Implications

Unique names must be unique.
Unique names must be carefully renamed according to our schema.
Updates must be done carefully to de-duplicate information.

Notes

The relationships schemata shown in these examples all have a column that distinguished between companions and antagonists. Looking at the example queries for selecting companion plants for groups it might be more efficient to split this table.

Drawing Library

Problem

The PermaplanT App needs a graphics library to build one of its core features using the canvas.

Constraints

Should work without WebGL etc.
The library must provide an easy-to-use API for creating and manipulating canvas elements.
The library should be well-supported and have a strong community.
The library should be able to import well-known raster formats.
Optionally, the library should also support drawing operations.
The library must be free software, compatible with our license.
The library must be compatible at least on Chromium and Firefox.
If the selected library does not have the necessary features, it is permitted to use another library in conjunction with it.

Assumptions

Considered Alternatives

HTML5 Canvas API:
The HTML5 Canvas API is a widely-supported and well-documented option for creating and manipulating 2D graphics in a web page. However, it provides a low-level API that may require more work to use than some of the other options. For example, the HTML5 canvas API does not provide a built-in support for grouping or layering elements which can make it more difficult to organize and manipulate complex graphic elements.
Raphaël:
Raphaël is a JavaScript library that provides a simple API for creating and manipulating SVG graphics. However, it may not be as well-suited for creating canvas-based graphics as some of the other options.
Pixi.js:
Pixi.js is a 2D graphics library that is designed for creating fast, interactive graphics for games and other applications. However, it relies on WebGL for rendering. One of the main disadvantages of WebGL is that it can be resource-intensive, as it relies on the GPU to render graphics and animations. In addition, WebGL requires a modern web browser that supports the API, which may not be available on older devices. This can limit the reach of applications that use WebGL. Furthermore, WebGL is not necessarily needed when creating a canvas-based application, as the HTML5 Canvas API and libraries built on top of it already provide a set of tools and functions for drawing and manipulating graphics on a canvas element.
Fabric.js:
Fabric.js is a JavaScript Library for creating and manipulating graphics and visual elements in web applications. Fabric.js is often used in applications that require the creation of complex graphics or visual elements, such as games, data visualizations, and interactive graphics. It is generally considered to be less performant than other alternatives like Konva especially when working with large numbers of objects. Additionally, Fabric.js does not have a built-in layering system like Konva.

Decision

We will use Konva as the 2D graphics library for the PermaplanT app.

Rationale

Konva is a well-supported and widely-used 2D graphics library that works in all browsers that are capable of running ES6 Javascript code. It has support for a wide range of features, including drawing shapes, text, and images, as well as transformations and animations. It is built on top of the HTML Canvas API and provides a higher-level, more declarative interface for creating and manipulating canvas elements. Additionally, it is very performant even with a large number of objects: Konva drag and drop with 10000 shapes stress test. It also has layer and opacity/transparency features.

Implications

Notes

Example Migrations

Normalized Plants and Ranks

2023-04-07-130215 Plant Relastionships

DROP TABLE plant_relationships; DROP TYPE relationship_kind; ALTER TABLE plants DROP COLUMN family_id, DROP COLUMN subfamily_id, DROP COLUMN genus_id, DROP COLUMN species_id; DROP TYPE taxonomic_rank;

CREATE TYPE taxonomic_rank AS ENUM ('family', 'subfamily', 'genus', 'species', 'variety'); ALTER TABLE plants ADD COLUMN rank TAXONOMIC_RANK NOT NULL, ADD COLUMN family_id INTEGER REFERENCES plants (id) NULL, ADD COLUMN subfamily_id INTEGER REFERENCES plants (id) NULL, ADD COLUMN genus_id INTEGER REFERENCES plants (id) NULL, ADD COLUMN species_id INTEGER REFERENCES plants (id) NULL;

CREATE TYPE relationship_kind AS ENUM ('companion', 'antagonist', 'neutral'); CREATE TABLE plant_relationships ( id SERIAL PRIMARY KEY NOT NULL, confidence INTEGER CHECK (confidence >= 0) NOT NULL, kind relationship_kind NOT NULL, left_plant_id INTEGER REFERENCES plants (id) NOT NULL, right_plant_id INTEGER REFERENCES plants (id) NOT NULL );

-- -- Example: Relationships

-- For this example we use the following notation -- companion "<->" -- antagonist ">-<" -- Consider the following relationships between plants: -- Radish <-> carrot -- Radish <-> potato -- Carrot >-< potato -- Marigold <-> carrot -- Marigold <-> radish

-- We want to plant carrots and radish and get suggestions for it. -- When looking for companions we would expect the result just to be marigold. -- Potato wouldn't be in the result since it's an antagonist to carrot.

-- Let's insert the plants. -- insert carrot WITH carrot_family AS ( INSERT INTO plants (rank, binomial_name) VALUES ('family', 'Apiaceae') RETURNING id ),

carrot_subfamily AS ( INSERT INTO plants (rank, binomial_name, family_id) VALUES ('subfamily', 'Apioideae', (SELECT id FROM carrot_family)) RETURNING id ),

carrot_genus AS ( INSERT INTO plants (rank, binomial_name, family_id, subfamily_id) VALUES ( 'genus', -- TODO: rename to latin_name 'Daucus', (SELECT id from carrot_family), (SELECT id from carrot_subfamily) ) RETURNING id ),

carrot_species AS ( INSERT INTO plants (rank, binomial_name, common_name, family_id, subfamily_id, genus_id) VALUES ( 'species', 'Daucus carota', '{"Carrot"}', (SELECT id from carrot_family), (SELECT id from carrot_subfamily), (SELECT id from carrot_genus) ) RETURNING id ),

-- insert radish radish_family AS ( INSERT INTO plants (rank, binomial_name) VALUES ('family', 'Brassicaceae') RETURNING id ),

radish_genus AS ( INSERT INTO plants (rank, binomial_name, family_id) VALUES ('genus', 'Raphanus', (SELECT id FROM radish_family)) RETURNING id ),

radish_species AS ( INSERT INTO plants (rank, binomial_name, common_name, family_id, genus_id) VALUES ( 'species', 'Raphanus raphanistrum', '{"Radish"}', (SELECT id from radish_family), (SELECT id from radish_genus) ) RETURNING id ),

-- insert marigold marigold_family AS ( INSERT INTO plants (rank, binomial_name) VALUES ('family', 'Asteraceae') RETURNING id ),

marigold_subfamily AS ( INSERT INTO plants (rank, binomial_name, family_id) VALUES ('subfamily', 'Asteroideae', (SELECT id FROM marigold_family)) RETURNING id ),

marigold_genus AS ( INSERT INTO plants (rank, binomial_name, family_id, subfamily_id) VALUES ( 'genus', 'Calendula', (SELECT id from marigold_family), (SELECT id from marigold_subfamily) ) RETURNING id ),

marigold_species AS ( INSERT INTO plants (rank, binomial_name, common_name, family_id, subfamily_id, genus_id) VALUES ( 'species', 'Calendula officinalis', '{"Marigold"}', (SELECT id from marigold_family), (SELECT id from marigold_subfamily), (SELECT id from marigold_genus) ) RETURNING id ),

-- insert potato potato_family AS ( INSERT INTO plants (rank, binomial_name) VALUES ('family', 'Solanaceae') RETURNING id ),

potato_subfamily AS ( INSERT INTO plants (rank, binomial_name, family_id) VALUES ('subfamily', 'Solanoideae', (SELECT id FROM potato_family)) RETURNING id ),

potato_genus AS ( INSERT INTO plants (rank, binomial_name, family_id, subfamily_id) VALUES ( 'genus', 'Solanum', (SELECT id from potato_family), (SELECT id from potato_subfamily) ) RETURNING id ),

potato_species AS ( INSERT INTO plants (rank, binomial_name, common_name, family_id, subfamily_id, genus_id) VALUES ( 'species', 'Solanum tuberosum', '{"Potato"}', (SELECT id from potato_family), (SELECT id from potato_subfamily), (SELECT id from potato_genus) ) RETURNING id )

INSERT INTO plant_relationships (kind, confidence, left_plant_id, right_plant_id) -- Radish <-> carrot VALUES ('companion', 1, (SELECT id FROM radish_species), (SELECT id FROM carrot_species)), -- Radish <-> potato ('companion', 1, (SELECT id FROM radish_species), (SELECT id FROM potato_species)), -- Carrot >-< potato ('antagonist', 1, (SELECT id FROM carrot_species), (SELECT id FROM potato_species)), -- Marigold <-> carrot ('companion', 1, (SELECT id FROM marigold_species), (SELECT id FROM carrot_species)), -- Marigold <-> radish ('companion', 1, (SELECT id FROM marigold_species), (SELECT id FROM radish_species));

-- Let's look for companions that go well with carrot and radish

-- First we get related plants which are not in the set we already have WITH potential_companions AS ( SELECT r1.left_plant_id AS plant_id, r1.kind FROM plant_relationships AS r1 WHERE r1.right_plant_id IN (4, 1) AND r1.left_plant_id NOT IN (4, 1) UNION SELECT r2.right_plant_id AS plant_id, r2.kind FROM plant_relationships AS r2 WHERE r2.left_plant_id IN (4, 1) AND r2.right_plant_id NOT IN (4, 1) )

SELECT * FROM plants AS p RIGHT JOIN potential_companions AS companions ON companions.plant_id IN (p.id, p.family_id, p.subfamily_id, p.genus_id, p.species_id) -- Then we need to remove companions are antagonists as well WHERE kind = 'companion' AND NOT EXISTS ( SELECT 1 FROM potential_companions AS antagonists WHERE kind = 'antagonist' AND companions.plant_id = antagonists.plant_id );

-- -- Example: Hierarchical Information (Varieties)

-- Let's say carrots have a height of 0.3m and a white flower colour. UPDATE plants SET mature_size_height = '0.3', flower_colour = 'white' WHERE binomial_name = 'Daucus carota';

-- Let's insert some varieteis. WITH carrot_species AS ( SELECT * FROM plants WHERE binomial_name = 'Daucus carota' ) INSERT INTO plants ( binomial_name, rank, family_id, subfamily_id, genus_id, species_id, mature_size_height, flower_colour ) -- There is a variety of it which grows higher but has the same flower_colour. VALUES ( 'Daucus carota var. magna', 'variety', (SELECT family_id FROM carrot_species), (SELECT subfamily_id FROM carrot_species), (SELECT genus_id FROM carrot_species), (SELECT id FROM carrot_species), '0.5', NULL ), -- And another variety which has the same height but yellow flowers. ( 'Daucus carota var. solis', 'variety', (SELECT family_id FROM carrot_species), (SELECT subfamily_id FROM carrot_species), (SELECT genus_id FROM carrot_species), (SELECT id FROM carrot_species), NULL, 'yellow' );

-- Get all plants and varieties while inheriting information for higher levels. SELECT p.id, p.binomial_name, COALESCE(p.mature_size_height, s.mature_size_height, g.mature_size_height, sf.mature_size_height, f.mature_size_height), COALESCE(p.flower_colour, s.flower_colour, g.flower_colour, sf.flower_colour, f.flower_colour) FROM plants AS p LEFT JOIN plants AS s ON p.species_id = s.id LEFT JOIN plants AS g ON p.genus_id = s.id LEFT JOIN plants AS sf ON p.subfamily_id = s.id LEFT JOIN plants AS f ON p.family_id = s.id WHERE p.rank IN ('species', 'variety');

One Table Per Taxonomy

2023-03-09-194135 Plant Relations

-- This file should undo anything in up.sql ALTER TABLE plants DROP CONSTRAINT plants_family_fkey; ALTER TABLE plants DROP CONSTRAINT plants_subfamily_fkey; ALTER TABLE plants DROP CONSTRAINT plants_genus_fkey; DROP TABLE IF EXISTS genus; DROP TABLE IF EXISTS subfamily; DROP TABLE IF EXISTS family; DROP TABLE IF EXISTS relations; DROP TYPE IF EXISTS RELATION_TYPE; DROP TYPE IF EXISTS HIERARCHY_LEVEL_TYPE;

-- Your SQL goes here CREATE TABLE genus ( id SERIAL PRIMARY KEY, name VARCHAR NOT NULL, created_at TIMESTAMP DEFAULT now() NOT NULL, updated_at TIMESTAMP DEFAULT now() NOT NULL, CONSTRAINT genus_name_key UNIQUE (name) ); CREATE TABLE subfamily ( id SERIAL PRIMARY KEY, name VARCHAR NOT NULL, created_at TIMESTAMP DEFAULT now() NOT NULL, updated_at TIMESTAMP DEFAULT now() NOT NULL, CONSTRAINT subfamily_name_key UNIQUE (name) ); CREATE TABLE family ( id SERIAL PRIMARY KEY, name VARCHAR NOT NULL, created_at TIMESTAMP DEFAULT now() NOT NULL, updated_at TIMESTAMP DEFAULT now() NOT NULL, CONSTRAINT family_name_key UNIQUE (name) ); ALTER TABLE plants ADD CONSTRAINT plants_genus_fkey FOREIGN KEY (genus) REFERENCES genus (name); ALTER TABLE plants ADD CONSTRAINT plants_subfamily_fkey FOREIGN KEY ( subfamily ) REFERENCES subfamily (name); ALTER TABLE plants ADD CONSTRAINT plants_family_fkey FOREIGN KEY (family) REFERENCES family (name); CREATE TYPE relation_type AS ENUM ('companion', 'antagonist', 'neutral'); CREATE TYPE hierarchy_level_type AS ENUM ( 'plant', 'genus', 'subfamily', 'family' ); CREATE TABLE relations ( id SERIAL PRIMARY KEY, from_id INTEGER NOT NULL, from_type HIERARCHY_LEVEL_TYPE NOT NULL, to_id INTEGER NOT NULL, to_type HIERARCHY_LEVEL_TYPE NOT NULL, relation_type RELATION_TYPE NOT NULL, relation_strength INTEGER NOT NULL, created_at TIMESTAMP DEFAULT now() NOT NULL, updated_at TIMESTAMP DEFAULT now() NOT NULL, CHECK ( relation_strength >= 0 AND relation_strength <= 3 ), CONSTRAINT relations_from_id_from_type_to_id_to_type_key UNIQUE ( from_id, from_type, to_id, to_type ) );

Taxonomy Ranks And Concrete Plants

2023-04-04-220813 Taxons

ALTER TABLE plants DROP COLUMN family_id, DROP COLUMN subfamily_id, DROP COLUMN genus_id, DROP COLUMN species_id; DROP TABLE taxons; DROP TYPE taxonomic_rank;

CREATE TYPE taxonomic_rank AS ENUM ('family', 'subfamily', 'genus', 'species'); CREATE TABLE taxons ( id SERIAL PRIMARY KEY NOT NULL, rank TAXONOMIC_RANK NOT NULL, name VARCHAR NOT NULL, icon_url VARCHAR NULL, parent_id INTEGER REFERENCES taxons (id) NULL );

-- TODO: drop taxonomic names in plants (family, subfamily, genus, species) ALTER TABLE plants ADD COLUMN family_id INTEGER REFERENCES taxons (id) NOT NULL, ADD COLUMN subfamily_id INTEGER REFERENCES taxons (id) NULL, ADD COLUMN genus_id INTEGER REFERENCES taxons (id) NOT NULL, ADD COLUMN species_id INTEGER REFERENCES taxons (id) NOT NULL;

2023-04-04-220921 Plant Relationships

DROP TABLE taxon_relationships; DROP TYPE relationship_kind;

CREATE TYPE relationship_kind AS ENUM ('companion', 'antagonist'); CREATE TABLE taxon_relationships ( id SERIAL PRIMARY KEY NOT NULL, strength INTEGER CHECK (strength >= 0) NOT NULL, kind relationship_kind NOT NULL, left_taxon_id INTEGER REFERENCES taxons (id) NOT NULL, right_taxon_id INTEGER REFERENCES taxons (id) NOT NULL );

2023-04-07-112305 Varieties

DROP TABLE varieties;

-- -- This illustrates how column overrides could be done for plant varieties. -- The example only shows how it would work for two columns. -- It could easily be extended to other columns.

CREATE TABLE varieties ( id SERIAL PRIMARY KEY NOT NULL, plant_id INTEGER REFERENCES plants (id), mature_size_height VARCHAR, flower_colour VARCHAR );

-- -- Example: Relationships

-- For this example we use the following notation -- companion "<->" -- antagonist ">-<" -- Consider the following relationships between plants: -- Radish <-> carrot -- Radish <-> potato -- Carrot >-< potato -- Marigold <-> carrot -- Marigold <-> radish

-- We want to plant carrots and radish and get suggestions for it. -- When looking for companions we would expect the result just to be marigold. -- Potato wouldn't be in the result since it's an antagonist to carrot.

-- Let's insert the plants. -- insert carrot WITH carrot_family AS ( INSERT INTO taxons (rank, name, parent_id) VALUES ('family', 'Apiaceae', NULL) RETURNING id ),

carrot_subfamily AS ( INSERT INTO taxons (rank, name, parent_id) SELECT 'subfamily', 'Apioideae', carrot_family.id FROM carrot_family RETURNING id ),

carrot_genus AS ( INSERT INTO taxons (rank, name, parent_id) SELECT 'genus', 'Daucus', carrot_subfamily.id FROM carrot_subfamily RETURNING id ),

carrot_species AS ( INSERT INTO taxons (rank, name, parent_id) SELECT 'species', 'Daucus carota', carrot_genus.id FROM carrot_genus RETURNING id ),

carrot AS ( INSERT INTO plants (binomial_name, common_name, family_id, subfamily_id, genus_id, species_id) SELECT 'Daucus carota', '{"Carrot"}', (Select id from carrot_family), (SELECT id FROM carrot_subfamily), (SELECT id from carrot_genus), (SELECT id from carrot_species) RETURNING id ),

-- insert radish radish_family AS ( INSERT INTO taxons (rank, name, parent_id) VALUES ('family', 'Brassicaceae', NULL) RETURNING id ),

radish_genus AS ( INSERT INTO taxons (rank, name, parent_id) SELECT 'genus', 'Raphanus', radish_family.id FROM radish_family RETURNING id ),

radish_species AS ( INSERT INTO taxons (rank, name, parent_id) SELECT 'species', 'Raphanus raphanistrum', radish_genus.id FROM radish_genus RETURNING id ),

radish AS ( INSERT INTO plants (binomial_name, common_name, family_id, genus_id, species_id) SELECT 'Raphanus raphanistrum', '{"Radish"}', (Select id from radish_family), (SELECT id from radish_genus), (SELECT id from radish_species) RETURNING id ),

-- insert marigold marigold_family AS ( INSERT INTO taxons (rank, name, parent_id) VALUES ('family', 'Asteraceae', NULL) RETURNING id ),

marigold_subfamily AS ( INSERT INTO taxons (rank, name, parent_id) SELECT 'subfamily', 'Asteroideae', marigold_family.id FROM marigold_family RETURNING id ),

marigold_genus AS ( INSERT INTO taxons (rank, name, parent_id) SELECT 'genus', 'Calendula', marigold_subfamily.id FROM marigold_subfamily RETURNING id ),

marigold_species AS ( INSERT INTO taxons (rank, name, parent_id) SELECT 'species', 'Calendula officinalis', marigold_genus.id FROM marigold_genus RETURNING id ),

marigold AS ( INSERT INTO plants (binomial_name, common_name, family_id, subfamily_id, genus_id, species_id) SELECT 'Calendula officinalis', '{"Marigold"}', (Select id from marigold_family), (SELECT id FROM marigold_subfamily), (SELECT id from marigold_genus), (SELECT id from marigold_species) RETURNING id ),

-- insert potato potato_family AS ( INSERT INTO taxons (rank, name, parent_id) VALUES ('family', 'Solanaceae', NULL) RETURNING id ),

potato_subfamily AS ( INSERT INTO taxons (rank, name, parent_id) SELECT 'subfamily', 'Solanoideae', potato_family.id FROM potato_family RETURNING id ),

potato_genus AS ( INSERT INTO taxons (rank, name, parent_id) SELECT 'genus', 'Solanum', potato_subfamily.id FROM potato_subfamily RETURNING id ),

potato_species AS ( INSERT INTO taxons (rank, name, parent_id) SELECT 'species', 'Solanum tuberosum', potato_genus.id FROM potato_genus RETURNING id ),

potato AS ( INSERT INTO plants (binomial_name, common_name, family_id, subfamily_id, genus_id, species_id) SELECT 'Solanum tuberosum', '{"Potato"}', (Select id from potato_family), (SELECT id FROM potato_subfamily), (SELECT id from potato_genus), (SELECT id from potato_species) FROM potato_species RETURNING id )

INSERT INTO taxon_relationships (kind, strength, left_taxon_id, right_taxon_id) -- Radish <-> carrot VALUES ('companion', 1, (SELECT id FROM radish_species), (SELECT id FROM carrot_species)), -- Radish <-> potato ('companion', 1, (SELECT id FROM radish_species), (SELECT id FROM potato_species)), -- Carrot >-< potato ('antagonist', 1, (SELECT id FROM carrot_species), (SELECT id FROM potato_species)), -- Marigold <-> carrot ('companion', 1, (SELECT id FROM marigold_species), (SELECT id FROM carrot_species)), -- Marigold <-> radish ('companion', 1, (SELECT id FROM marigold_species), (SELECT id FROM radish_species));

-- Let's look for companions that go well with carrot and radish

-- First we get related plants which are not in the set we already have WITH potential_companions AS ( SELECT r1.left_taxon_id AS taxon_id, r1.kind FROM taxon_relationships AS r1 WHERE r1.right_taxon_id IN (3, 7) AND r1.left_taxon_id NOT IN (3, 7) UNION SELECT r2.right_taxon_id AS taxon_id, r2.kind FROM taxon_relationships AS r2 WHERE r2.left_taxon_id IN (3, 7) AND r2.right_taxon_id NOT IN (5, 7) )

SELECT * FROM potential_companions companions LEFT JOIN taxons AS t ON companions.taxon_id = t.id LEFT JOIN plants AS p ON t.id IN (p.family_id, p.subfamily_id, p.genus_id, p.species_id) -- Then we need to remove companions are antagonists as well WHERE kind = 'companion' AND NOT EXISTS ( SELECT 1 FROM potential_companions antagonists WHERE kind = 'antagonist' AND companions.taxon_id = antagonists.taxon_id );

-- -- Example: Hierarchical information

-- Let's set an for the family of potato and one for the carrot species. UPDATE taxons SET icon_url = '/assets/img/solanaceae.png' WHERE name = 'Solanaceae'; UPDATE taxons SET icon_url = '/assets/img/daucus_carota.png' WHERE name = 'Daucus carota'; -- Get all plants with their hierarchy information SELECT plants.common_name, species.name, genus.name, subfamily.name, family.name, COALESCE(species.icon_url, genus.icon_url, subfamily.icon_url, family.icon_url) AS icon_url FROM plants LEFT JOIN taxons AS species ON (species.rank = 'species' AND species.id = plants.species_id) LEFT JOIN taxons AS genus ON (genus.rank = 'genus' AND genus.id = plants.genus_id) LEFT JOIN taxons AS subfamily ON (subfamily.rank = 'subfamily' AND subfamily.id = plants.subfamily_id) LEFT JOIN taxons AS family ON (family.rank = 'family' AND family.id = plants.family_id);

-- -- Example: Varieties

-- Let's say carrots have a height of 0.3m and a white flower colour. UPDATE plants SET mature_size_height = '0.3', flower_colour = 'white' WHERE binomial_name = 'Daucus carota';

-- There is a variety of it which grows higher but has the same flower_colour. INSERT INTO varieties (plant_id, mature_size_height) VALUES ((SELECT id FROM plants WHERE binomial_name = 'Daucus carota'), '0.5');

-- And another variety which has the same height but yellow flowers. INSERT INTO varieties (plant_id, flower_colour) VALUES ((SELECT id FROM plants WHERE binomial_name = 'Daucus carota'), 'yellow');

-- Get all plants without varieties. SELECT id, binomial_name, mature_size_height, flower_colour FROM plants;

-- Get all varieties. SELECT v.id, p.binomial_name, COALESCE(v.mature_size_height, p.mature_size_height), COALESCE(v.flower_colour, p.flower_colour) FROM varieties AS v LEFT JOIN plants p ON v.plant_id = p.id;

-- Get all plants and varieties. SELECT p.id, p.binomial_name, p.mature_size_height, p.flower_colour FROM plants AS p UNION SELECT v.id, p.binomial_name, COALESCE(v.mature_size_height, p.mature_size_height), COALESCE(v.flower_colour, p.flower_colour) FROM varieties AS v LEFT JOIN plants p ON v.plant_id = p.id;

Frontend Architecture Pattern

Problem

PermaplanT needs to be designed with a documented, consistent and maintainable architecture pattern.

Constraints

The architecture pattern should be

easy to understand and follow
be easy to test
be easy to scale
be suitable for a large, highly-interactive application
promote code reuse
be well-documented and widely used in the React community

Considered Alternatives

Flux

The pattern is rather complicated to understand and leads to a lot of boilerplate.
MVVM

Decision

Bulletproof React will be used as frontend architecture and guideline for PermaplanT. Choices or derivations of this guidelines will be documented in our architecture.

Rationale

Bulletproof React is a set of best practices and conventions that promote code reuse and make it easy to reason about the structure of the application. It's simple, easy to understand, and easy to test. This makes it a good choice for a large, complex application like PermaplanT. Additionally, it is well-documented and widely used in the React community, which means that there is a lot of resources and support available for it.

Implications

Notes

"bulletproof react" architecture pattern is developed by the team at Level Up Tutorials. It is not an official pattern by React.

Frontend Build Tool

Problem

We need to choose a build tool for the React frontend of our application that can bundle various types of assets, such as JavaScript, CSS, and images that can be efficiently loaded by the browser.

Constraints

The build tool must provide optimization features such as tree shaking to reduce bundle size.
The build tool must have good documentation and a large community of users.
The build tool should provide good performance and fast build times.

Assumptions

The build tool's learning curve will not be too steep for the development team.
The build tool will not add unnecessary bloat to the app.

Considered Alternatives

Webpack: Webpack is a popular and widely-used build tool that has good support for React. It has a large plugin ecosystem and can handle a wide range of use cases. However, it can have a steep learning curve and may require a lot of configuration to set up.
Rollup: Rollup is focused on providing efficient tree-shaking and code-splitting to reduce bundle size. It has a simpler configuration than Webpack and a good support community.
Parcel: Parcel is a newer build tool that is known for its simplicity and fast performance.

Decision

We will use Vite as the build tool for the React frontend of our application.

Rationale

In general, Vite offers a faster and more efficient development experience. It serves individual ES modules to the browser during development, allowing it to start up nearly instantly. Hot Module Replacement(HMR) only needs to replace one small file instead of rebundling the entire app, making rebuilds quick. Vite also uses Rollup underneath for production builds to perform an aggressive dead-code elimination (tree shaking), which in general results in smaller bundle sizes.

Implications

Notes

Frontend Documentation

Problem

We need to choose a workflow, tooling that helps us to keep the documentation up to date. An easy-to-read and up-to-date documentation reduces the entry barrier for newcomers. Without proper documentation maintenance becomes increasingly more difficult as the project grows.

Constraints

The documentation should be easy to navigate.
The documentation should, for the most part, be automatically extracted from the source code.
The documentation should be searchable.

Assumptions

With a good and beautiful documentation tool, developers are more likely to use and maintain it.
With a documentation tool that enables the viewing of react components, the code quality is improved.
The rules about component design in contrib/frontend are followed.
With an overview of all presentation components, the whole team can instantly see what is available.

Considered Alternatives (documentation extraction)

API-Extractor: API-Extractor is a tool to extract the public API of a typescript project. It is more suited for libraries.
React Docgen: React Docgen is a tool from the React Community to extract information from React Components for documentation generation purposes.
- It is not actively maintained anymore.
- It does not generate markdown files, so an additional step is needed, to get just the most basic information.
JSDoc: JSDoc is an API documentation generator for JavaScript. It is more suited for JavaScript.

Decision

We will use TypeDoc with the markdown plugin to extract documentation from the source code.

Rationale

TypeDoc has automatic support for most tags of JSDoc via the TypeScript compiler.
Additional tags are supported as well.
It is easy to configure and invoke.
It is extensible via plugins.

Considered Alternatives (viewing components)

React Styleguidist: React Styleguidist Is a popular and maintained solution to develop a project-wide style guide in React. It has fewer features than Storybook. It is hard to setup, as it assumes the usage of Create React App.
Docusaurus: Docusaurus Is a popular solution for generating static documentation websites. It is more targeted towards manually written documentation and has less features specifically targeting how a component should be used.

Decision

We will use Storybook to enable a project-wide component overview and style guide. It has support for MDX, a format that enables embeddable components in Markdown. It has support for automated testing via Vitest and Playwright.

Rationale

With Storybook the extracted documentation from TypeDoc can viewed as standalone documentation pages. It works well with Vite and is relatively easy to setup.

Implications

To install storybook a .npmrc file with legacy-peer-deps=true is required. This causes npm to behave like in version 6, not installing peer-dependencies automatically. This should not cause any problems down the line, but storybook could be extracted into it's own package, with more configuration involved.
A little plugin needs to be developed to link Storybook and the extracted markdown files from TypeDoc automatically.

Notes

Notes about embedded markdown

Without the plugin, we will need to write a .mdx file for each extracted markdown file. Also links inside the markdown will not work without the plugin.

import Md from './docs/enums/bindings_definitions.Quality.md';
import './markdown.css';
import { Description, Meta } from '@storybook/addon-docs/blocks';
import React from 'react';

<Meta
  title="Enumeration: Quality"
  parameters={{
    viewMode: 'docs',
    previewTabs: {
      canvas: { hidden: true },
    },
  }}
/>

<Md />

How to structure a storybook

https://storybook.js.org/blog/structuring-your-storybook/

E2E Testing

Problem

There is currently no existing e2e tests locally and in the pipeline. This allows for increased frontend bugs and regression. It lacks profound decision making which framework to pick.

Constraints

Behavior-driven development
- a) We want to have .feature files and stick to the Gherkin syntax.
Page Object Design Pattern
- a) A programming language that supports classes
The library must be free software.
A minimalistic and simplistic solution (little lines/characters).
The framework must have an active community.
Headless browser support so we can run the tests in our automated pipeline.

Assumptions

Understanding of BDD practices and principles, including writing feature files using the Gherkin syntax.
Familiarity with the Page Object Design Pattern and its implementation for creating modular and maintainable test code.
Knowledge of end-to-end testing concepts and best practices.
Basic understanding of Python programming language and its syntax.
Having heard of pytest and its usage for test execution and assertions.

Solutions

Java + Selenium

Java with Selenium is a popular and well-established choice for web test automation. While it remains a reliable option, there are personal preferences and concerns about Oracle's licensing changes, and there are other languages that can do the same with less boilerplate.

Typescript + Playwright

Typescript with Playwright is a powerful combination for web test automation. However, concerns regarding potential code complexity and the temptation to write complicated workarounds influenced the decision to avoid Typescript as the testing language (see Constraint 4).

Typescript + Cypress

Similar to Playwright, Cypress is another Typescript-based test automation framework. However, it was not chosen due to the same concerns about Typescript mentioned earlier.

Robot Framework

The Robot Framework, while supporting Python and following BDD principles, has its own syntax and separate resource file management, which contradicts the first constraint of the project. On top of that it is not really used in the fields of frontend testing, even though it has a separate web testing library. The information regarding this library is scarce on the internet, and this might cause problems. According to @4ydan it has a steeper learning curve, because not only does it introduce a Gherkin similar syntax but also drives its tests with keywords, which conflicts with the desire for an easy-to-learn and minimal solution. @markus2330 didn't find it difficult to learn.

Puppeteer

Puppeteer is a viable alternative to Playwright, as it also provides automation capabilities for Chrome and Chromium-based browsers. However, the decision to use Python as the programming language led to the preference for Playwright for Python.

Python + Selenium + Behave

Python with the Behave framework is capable of fulfilling the requirements. However, pytest-bdd was preferred over Behave due to its integration with pytest and the added feature of parallel test execution, which should give the low performance stack a slight boost. Playwright was preferred over Selenium because it was easier to install and the browser integration into python was way smoother.

Decision

We use Playwright for Python as the test automation framework. Python's readability, ease of use, and extensive ecosystem make it a solid choice for test automation.

Additionally we will need the following libraries:

Rationale

Python

Introducing a new language and gherkin to the stack might at first sound challenging and not make much sense, but this decision has a reasoning. I prefer Python over Typescript because Python is easier to maintain and read in the long run. You can solve the same problems in any of the frameworks, so why not chose the simplest one? One could argue that simplicity and preference is relative, discussing that would go beyond the scope of this document.

Playwright

Playwright for Python offers comprehensive browser automation capabilities, aligns well with Python's syntax and ecosystem, and satisfies the project's constraints and requirements. Additionally, Playwright for Python provides a very clear documentation, which makes it easier for developers who are not so experienced with frontend testing, to get started quickly. Furthermore the projects performance tests and scraper utilize playwright, which makes it fit good.

Gherkin

Choosing to have the Gherkin syntax is adding an extra step to writing tests but with a clear benefit which I will mention later. Furthermore the Gherkin syntax can be reused with other frameworks if Playwright and Python want to be replaced.

BDD

Behavior Driven development (BDD) is an agile software development methodology that aims to align the development process with the desired behavior of the software. By using BDD, tests can be written in a format that is easily understood by domain experts, enabling the collaboration and effective communication between them and developers. Given PermaplanT's close collaboration with permaculture domain experts, the adoption of BDD is beneficial for the project, as it enables clear communication and alignment between the development team and domain experts. Additionally, BDD fits seamlessly with the already established agile development practices of the development team.

POM

Page Object Models (POMs) are a valuable concept when it comes to improving code complexity in test automation. POMs help to separate concerns and encapsulate the functionalities of individual pages or components. This approach encourages developers to write more modular and maintainable code, as each page object represents a specific page or component and contains the associated actions and assertions. By utilizing POMs, the codebase becomes more organized, easier to read, and simpler to maintain, ultimately enhancing the overall quality of the test automation framework.

This solution has probably a steep learning curve, but once getting the hang of it, implementing tests becomes very easy.

Implications

Write Guidelines for writing these Tests (BDD/POM, TDD, etc.).
Write Guidelines on how to write a testable frontend.

Notes

@4ydan

Frontend Keyhandling

Problem

In the development of PermaplanT, we have identified the need for a robust keybinding system to enhance the developer experience. During research we considered to use some npm packages that provide keybinding functionality.

Constraints

Our keybinding solution should adhere to the following constraints:

Developer-friendly: Developers should get an overview where which key binding is assigned.
Ease of Integration: The keybinding system should be straightforward to integrate into different components of the application.
UX: Collisions between shortcuts which trigger multiple actions at once should be avoided.

Solution

React-hotkeys

Link: react-hotkeys
provides a component that receives a keymap and actionhandlers and listens to events if a child of the component is in focus.
It seems to be very suitable for encapsulating events
however, it doesn't really solve the challenge of focus konva layers
and although the library is widely used the last release was 4 years ago.

React-hotkeys-hook

Link: react-hotkeys-hook
provides a hook for binding keys in components and also
offers scoping abilities.
however, integration seems not to be as straightforward as with a custom solution and so it doesn't really solve a problem for us.

Decision

We don't use any of the packages.
Guideline: /doc/guidelines/frontend-keyhandling.md

Rational

We already have a custom keybinding hook and currently don't need any of the features provided by the packages.
The custom hook gives us more flexibility and is easier to integrate into our components.

Frontend Lazyloading

Problem

The application's main component is the map, which consists of multiple layers and even more elements. The map does not only consist of elements for the current date, but also for the past and future dates. Not all layers or elements are visible simultaneously, however, nor are they required during the initial loading of the application.

Loading all the data at once during the initial load may result in slower performance, therefore a strategy must be developed to lazyload data on the map to optimize its performance. In other words, the data which is not required for the user to start working with the map should not be loaded during the startup.

Constraints

Fast startup time
Supports performance constraints of the usecases

Assumptions

The majority of layers are only modified once a year
The loading of all the data at once during the initial load would result in unacceptable performance

Solutions

Full fetch

Fetching all the data from the backend during the initial load, while making the map available immediately, may not be the most optimal solution as it would lead to a slower initial load time.

Compared to the other solutions, network traffic would be higher due to the larger payload, and the user may have to wait longer before being able to interact with the map.

Pagination

If map data would be stored in a single table with uniform entries in a database, we could use pagination to retrieve the data in sections. This approach would enable loading only the essential data during the initial load by fetching a specific portion i.e. page of the data.

However, since the canvas data is structured in a nested manner, we cannot implement the same approach of fetching data in sections as we would do with a flat array structure.

SQL VIEW tables

To avoid fetching unnecessary data during the initial load, an SQL view could be created on the database side i.e. return only visible layers for the current date.

Implementing this solution, however, would require writing additional SQL queries. This may not be the most efficient approach since the same outcome can be achieved through the parameterized backend (which is using the rust query builder anyway) endpoints described below in the final solution.

Decision

In order to improve the performance of the application's initial load, it is advisable to load only the necessary data and load the rest on demand. The most effective way to achieve this is through the backend, which can define endpoints with additional parameters that allow the frontend to request only the required data for the initial load:

separate endpoints for different layers
have date as parameter to these endpoints so that only the current relevant elements (already added, not yet removed) can be retrieved

Rationale

Creating endpoints with additional parameters that allow the frontend to request only the required data for the initial load is a more flexible way to implement lazy loading compared to other approaches. This will allow backend developers to define the strategy themselves and have full control over the data that is being loaded.

The following table is the outcome of the performance tests that were conducted by measuring the loading times of the application with different number of elements and layers on the map. As it can be seen, the number of layers does not have a significant impact on the loading time, however, the number of elements does.

Test name	firstContentfulPaint (ms)	interactive (ms)
empty canvas	4971.2	6184.8
3 elements	4968.6	6232.8
3 circles of same shape	4966.2	6266.8
100 circles	4966.6	6175.6
1000 circles	4690	7634.6
10000 circles with 1 layer	4963	26389.2
10000 circles with 10 layer	4958.4	26790.6

Implications

N/A

Notes

Performance tips from KonvaJS: https://konvajs.org/docs/performance/All_Performance_Tips.html
Drag and Drop Stress Test with 10000 Shapes https://konvajs.org/docs/sandbox/Drag_and_Drop_Stress_Test.html

Frontend API Mocking Tool

Problem

We need to select an API mocking tool for our frontend development that allows us to simulate API responses for testing and development purposes.

Constraints

The selected tool should seamlessly integrate with our frontend development environment.

Assumptions

Considered Alternatives

MSW (Mock Service Worker): MSW is a popular API mocking tool for react applications. It intercepts requests on network level so that code can be tested the same way it is executed in production. Frontend devs can also use msw for development so that they don't have to wait for the backend to be ready.
Nock: Nock is also a very popular alternative for API mocking and according to some developers in forums, it is easier to set up than MSW. MSW, however, seems to be a more React-centric approach and Nock can only be used with Node.js and not in the browser.
MirageJS: MirageJS provides pretty similar functionality to MSW, but it is not as widely used.

Decision

We have decided to use MSW (Mock Service Worker) as our API mocking tool for frontend development.

Rationale

All the considered alternatives are powerful tools for API mocking, but MSW is widely used by the community and has a lot of documentation and tutorials available.

Some key advantages of using MSW for API mocking include:

Request Interception and Mocking: MSW provides a powerful request interception and mocking system, allowing us to simulate various API scenarios, including different response codes, payloads, and latency.
Active Community and Documentation: MSW has a thriving community and comprehensive documentation, which will aid our team in quickly learning and effectively using the tool.

Implications

Our development team will need to become familiar with MSW's usage and configuration to effectively use it for API mocking.
Integration of MSW into our existing development tools and pipelines will be necessary.

Notes

Frontend Offloading

Problem

As the user continues to add more layers and objects to the map, it may lead to slower performance and increased memory usage on the client side. To avoid this, a strategy must be developed to offload the data that has already been synchronized with the backend from the frontend.

Constraints

Memory usage should be kept to a minimum to avoid performance issues
The application should be able to handle large amounts of data

Assumptions

Users typically don't do changes across all years.
Users might be invited to activate many layers for a short time due to gamification.
Memory issues only occur when having many layers active and not because of a single layer.

Solutions

No Offloading

The state of the frontend application will be kept in the React state without offloading it.

The maximum size of the React state is not explicitly defined in the official documentation, but it is related to the device's RAM and the browser's memory usage.

Remove Unused Elements from the Frontend State

One solution to offload data from the frontend state is to remove the data that is not frequently required for the user to continue working with the map. This approach can increase the application's complexity, however, as it requires:

defining the conditions under which data should be removed from the state. E.g. offload data that is not visible on the map or offload data that is not required for the currently selected date.
how to retrieve the data again.

Store Data in IndexedDB

Another solution is to store the offloaded data in IndexedDB, which is a browser-based object-oriented database.

This approach could reduce memory usage and improve performance, as objects can be offloaded and loaded on-demand from the IndexedDB, while not storing them in the PermaplanT database. But this method increases the complexity of the application, as it requires additional strategies to manage the synchronization of data between the IndexedDB and the PermaplanT database.

The official documentation of IndexedDB can be found here.

Decision

We offload layers with the highest amount of objects that were not used for a longer time (~15 min) from the frontend state.

Furthermore, we keep the state as structured as possible

Rationale

While similar to remove unused elements, per layer is a more efficient:

only a few rules are needed: only per layer and only for the layers with many elements
tracking when the layer was activated last time is much easier than tracking individual elements

The disadvantage of this approach is, that it cannot scope with memory issues within a single layer. (Or only indirectly: if a layer gets offloaded, then also all years of that layer are discarded.)

Even though modern browsers handle memory usage well, it's important to consider the impact of the state size on application rendering. React utilizes a virtual DOM(The Document Object Model i.e. DOM) that's a copy of the real DOM, and it compares them when the state changes to update only the necessary parts of the real DOM. As a result, if the entire map information is stored in a single object, any state changes (e.g. changing the position of an object) will require updates to every element of the real DOM, which depend on the map information i.e. the entire map. Therefore, keeping the state as structured as possible in it can help optimize application rendering.

Implications

Undo/redo functionality: Once the data is offloaded and permanently removed from the frontend state, it can't be retrieved to utilize the undo/redo functionality anymore. So for the undo/redo functionality, it will be the same as the fresh start of the application. I.e. for layers that were offloaded, undo/redo is lost.
Structured state: As there is no offloading within a layer, we need to keeping the state as structured as possible to avoid performance issues.

Map undo redo implementation

Notes

IndexedDB. Mozilla Developer Network (MDN) documentation on IndexedDB:

https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API

Polygon Libraries

Problem

For drawing areas of shadings, hydrology, zones, etc., we need to transform a set of points, drawn using a brush, into a polygon. Furthermore, we want to be able to create unions of polygons so that areas can be expanded and differences of polygons to reduce areas.

Constraints

Algorithms need to be fast enough so that users won't recognize any delays.

Assumptions

We assume that there are no alternative packages readily available that offer significantly better performance or features than the ones we have explored.

Solutions

graham_scan

graham-scan is an implementation of the Graham Scan algorithm to calculate a convex hull from a given set of points.

Easy to integrate.
It only provides convex hull calculation.

hull.js

hull.js provides functions for calculating convex and concave hulls from a given set of points.

Concavity can be configured by a parameter.
Very easy to integrate.
Fast calculation.

polygon-clipping

polygon-clipping provides boolean polygon operations like intersection, union, and difference.

Well maintained.

Further packages

There are several other packages like flatten-js/boolean-op. However, most of them haven't been updated in a long time.

Note: Click here to see an image that shows the difference between convex and concave hulls.

Decision

We decided to use hull.js for calculating hulls and polygon-clipping for union operations.

Rationale

Hull Calculation

hull.js is very easy to integrate. We already tested it in the drawing layer and it was easy to calculate a polygon by passing a set of drawn points.
The calculation is very fast.
We can configure how precisely the polygon should match the drawn shape.

Boolean Operation

polygon-clipping provides all the operations we need to unify polygons and it is regularly updated.

Frontend Programming Language

Problem

The PermaplanT app needs a frontend programming language to build its user interface and provide interactivity for its users.

Constraints

The programming language must be widely supported and have a large developer community.
The frontend language must be compatible with modern web browsers, including Firefox and Chromium.
The language must be easy to learn and use, to allow for a range of skill levels among developers.
The language must have good support for modern web technologies like HTML5 and CSS3.
The language must be suitable for use in a PWA environment.
We want to use a typed language to improve maintainability and catch errors earlier in the development process.

Assumptions

The use of TypeScript as a frontend programming language will enable the app to be developed quickly and efficiently.
TypeScript has a large and active developer community, which will provide support and resources for the development of the app.
The use of TypeScript will enable the creation of visually appealing and interactive user interfaces.
TypeScript will provide sufficient type checking to improve the maintainability of our codebase.
TypeScript will not significantly impact the performance of our application.

Considered Alternatives

JavaScript: JavaScript is the default language for React, and the most commonly used language for frontend development. However, JavaScript is a dynamically typed language, which can make it error-prone and less maintainable in the long term.
Rust: Rust is primarily used for creating backend systems, applications, and libraries. It is not typically used for frontend development, as it does not have built-in support for graphical user interface development. Libraries like yew are simply not stable enough yet. See also this lengthy comparison of web UI libraries.

Decision

We will use TypeScript 4.9.3 as the frontend programming language for app.

Rationale & Implications

TypeScript is a statically-typed language that is a superset of JavaScript, meaning that it includes all the features of JavaScript in addition to additional type-related features. This can help improve the overall quality and maintainability of the codebase by catching potential errors at compile-time rather than runtime, as well as enabling better editor support and code navigation. Additionally, TypeScript's type system allows for the creation of more scalable and reusable code, as well as easier refactoring and code review processes. In comparison to other frontend languages, TypeScript offers a strong balance between the benefits of static typing and the flexibility and familiarity of JavaScript, making it a suitable choice for the PermaplanT app.

The app will be able to take advantage of the large ecosystem of libraries and resources available for TypeScript development.

The decision to support multiple platforms and browsers.
The decision to prioritize a smooth and interactive user experience.
Decision: Frontend UI Framework

Notes

Frontend State Management

Problem

PermaplanT is a web application built with React that requires efficient and flexible state management. Inside a React application we can usually distinguish between three types of state:

Local Component State: Is the dropdown open or not, is the link active or not, and so on.
Global Application State (Synchronous): Local user preferences, Sidenav is open, UI state in a visual design app.
Server State (Asynchronous): A network request is needed before any state can be derived.

Constraints

The state management library must support React and work seamlessly with the rest of the application's technology stack.
The library should be well-maintained, have a large community of developers, and a good documentation.

Considered Alternatives

Global Application State

Redux Requires more complex setup, boilerplate and has a steeper learning curve than Zustand.
React context Requires complex custom state management solution for complex application
MobX Requires basic understanding of reactive programming - may otherwise lead to inconsistencies and performance problems.
Recoil Recoil is still in experimental state, not yet recommended for production (16.03.2023).

Server State

SWR Fewer features than React Query

Decision

Local Component State

No library is needed.

Managing component state can be accomplished with React features (useState, Context + useReducer).

Global Application State

Zustand will be used as the global state management library for PermaplanT.

Zustand is a lightweight and easy-to-use library that uses hooks, which makes it easy to integrate with React. Its simplicity also reduces the amount of boilerplate code and the need for complex setup and configuration.

Zustand also provides the Persist middleware which enables storing state in any type of storage. Another benefit of Persist is the serialization and deserialization support for fields of type Map and Set.
Persist's partialize method can be used to store only selected fields of the state.

Server State

TanStack React Query v4 will be used for managing asynchronous state.

React Query is a feature rich, up-to-date library for managing asynchronous data.

Implications

Choosing React as the frontend library for PermaplanT

Notes

Timeline: Custom Date Picker Implementation Decision

Problem

To implement the timeline feature, we require a custom date picker capable of displaying indicators for plant additions and removals.

Constraints

Timeline should be user-friendly and intuitive
event indicators can be shown on the timeline

Solutions

Initially, the team considered using ReactCharts, a powerful charting library. However, it is not designed for date selection because of following reasons:

React-Charts is a robust library for rendering various charts and graphs, but it lacks the precise date selection functionality required for this project. Customizing the library for date selection may prove complex and may not deliver the desired user experience.
React-Charts, designed for data visualization, might introduce unnecessary complexities for date selection.

As a result, we have decided to create custom components for building the timeslider.

Decision

The custom timeline will consist of following components:

Picker Slider: A draggable and scrollable slider where the middle element is the selected one. The elements displayed on the slider can also be customized to accommodate event indicators for each date.
Date Picker Component: This component will consist of three sliders for year, month, and day selection. It will be responsible for synchronizing the sliders and calculating data for event indicators. Event indicators will be simple bars or divs – a green one for plant additions and a red one for removal – resembling a mini bar chart.

Rationale

A dedicated date picker offers a simplified user interface, ensuring intuitive date selection.
Customization enables us to design a date picker that precisely matches the project's visual style and UI/UX requirements. It can seamlessly integrate into the application's design language.
The custom date picker will employ basic HTML elements for representing event indicators. This approach simplifies event rendering on the date picker, allowing for easy placement and styling of event markers without the need for a comprehensive charting library.

Frontend UI Framework

Problem

We need to choose a UI framework for the PermaplanT app that will enable us to create a beautiful and easy-to-use interface and that is well-suited for building PWAs with JavaScript.

Constraints

The framework must be compatible with the PWA architecture.
The framework must be able to handle complex, data-intensive operations such as checks for sun, soil, companion/antagonist and time of year.

Assumptions

React is a popular and widely-used framework for building user interfaces, which means that there will be a large community of developers available to help with any issues that arise.
React allows for the creation of reusable components, which will be useful for building the various modes and features of the PermaplanT app.
React is fast and efficient, which will be important for providing users with a smooth and responsive experience.

Considered Alternatives

Decision

We will use React (18.2.0) as the frontend ui framework for app.

Rationale

React is a popular JavaScript library for building user interfaces, and it is a good choice for building progressive web apps (PWAs) for several reasons. Some of the key advantages of using React for PWAs include its performance, flexibility, and developer-friendly ecosystem. React uses a declarative approach to building user interfaces, which makes it easy to create complex and interactive PWAs. Additionally, React has a large and active community of developers, with a wealth of resources and tools available, such as libraries, components, and tutorials.

Implications

The decision to use a declarative and component-based approach for the app's UI

Notes

Map Undo/Redo Implementation

Problem

Undo/redo functionality is a common feature in many applications, PermaplanT is no exception. The user should be able to undo/redo the actions taken within the canvas.

Constraints

The implementation of undo/redo should not have a significant impact on the performance of the app.
The implementation of undo/redo should correspond to the related use case

Assumptions

N/A

Solutions

Store every step of the user in the database

The idea is to store every step of the user taken within the canvas in the database. The user can then undo/redo the actions by fetching the previous/next step from the database. The user is working with the canvas locally, but the state of the canvas is stored in the database. The main drawback of this approach is that the database will grow significantly over time. We have to store the entire state of the canvas for every step taken by the user. This could lead to performance issues in the future.

Let's assume that there are 1000 users using the app. We have ~19 layers in the app. If the user places 10 shapes on each layer and modifies the properties of each shape 3 times, we have 570 actions taken by the user for each layer. If we store the entire state of the canvas for every action taken by the user, we have 10,830 actions stored in the database for each user. If we have 1000 users, we have 10,830,000 actions stored in the database for a single day. This number will grow drastically over time.

Alternatively, storing only the final state of the canvas in the database would result in a much smaller number of entries. Since there is only one entry per map, we would have a maximum of 1000 entries for the same amount of users for a single day or even for a longer period of time.

Manual and Periodic Syncs

We could implement undo/redo functionality by storing all intermediate states of the canvas on the frontend and only storing the final state in the database.

To keep the backend state in sync with the frontend, a manual and periodic sync strategy will be used according to some custom rule, rather than an immediate sync every time the user takes an action on the canvas. This avoids the potential for delays and performance issues caused by excessive processing and network traffic. Instead, syncing periodically ensures up-to-date data while minimizing network traffic and data transfer costs. The periodic sync approach allows the user to work locally on the canvas, reducing the performance impact of storing and retrieving data from the database.

When the app is refreshed, the frontend will rebuild the map from scratch based on the data fetched from the backend.

This approach is not used, as it endures conflicts: In two bundles send at the same time, conflicting actions might be present. Furthermore, data might be lost on browser crashes etc.

This could be mitigated by having very short periodic syncs but then the wanted benefit of this approach does not apply anymore, too.

Decision

The decision is to implement undo/redo functionality by storing history of the canvas only in the frontend and having the current state both:

in the backend: stored in the database, without any history
in the frontend: stored as state, with additionally a history of previous actions

Synchronisation happens:

Any change of the frontend immediately gets synced to the backend via API calls.
Any change in the backend immediately gets synced to the frontend via a server-sent events (SSE).

In the backend, we use the observer pattern to implement the notification via SSE.

Rationale

It is the most collaborative way: Users immediately see what other users did.
It is the most user friendly way: No manual saving or no intransparent sync times

Implications

As undo/redo steps might be in conflict with what other users did, conflicting undo/redo steps must be filtered.
The backend API must be designed that the whole user action is encapsulated in a single API call.

Frontend State Management

Notes

The canvas library, that we use, provides a suggestion on how to implement undo-redo functionality with the canvas²:

https://konvajs.org/docs/react/Undo-Redo.html
https://konvajs.org/docs/data_and_serialization/Best_Practices.html#page-title

If you want to save/load simple canvas content you can use the built-in Konva methods: node.toJSON() and Node.create(json). But those methods are useful only in very small apps. In bigger apps it is VERY hard to use those methods. Why? Because the tree structure is usually very complex in larger apps, you may have a lot of event listeners, images, filters, etc. That data is not serializable into JSON (or it is very hard to do that).

In other words, the Konva nodes contain too much information e.g. color or shape which could be set by default. So there is no reason to store them in the database if they are set by default by Konva anyways. Instead, we should only store the information that the user has changed.

You just need to save a history of all the state changes within your app.

Implementing the undo/redo functionality on the frontend, as suggested above, provides a simpler and more efficient solution than storing every step of the user in the database. Storing intermediate states of the canvas in the frontend store allows the user to work locally in the canvas without significant performance impact. Additionally, syncing the backend state with the frontend state periodically ensures that the user's data is always up-to-date.

Reversible deletion of database entities

Problem

PermaplanT provides functionality not only to delete entities created by the user, e.g. plants, maps, etc. but also to restore them within a period of time. This is required to prevent the accidental deletion of entities and to allow users to undo their actions. The challenge is to keep the deleted entities for a certain period of time, e.g. 1 month, and then remove them from the database on a scheduled basis. Since there is no built-in time-based job handling feature(like cron jobs in Unix systems) in PSQL, we cannot simply mark entries to be removed and expect them to fade away.

Constraints

The decision applies only to the map and plant entities for the time being.

Assumptions

N/A

Solutions

PSQL partitioning

Partitioning is a feature of PSQL that allows to split a table into smaller tables based on a certain column value. If we would proceed with the partitioning based on a deletion timestamp column, we can run the partitioning process either manually every day, which is a 100% no-go for us, or assign it to a PSQL trigger. Unfortunately, there are only on- INSERT/UPDATE/DELETE and no time-based triggers in PSQL. Therefore, we could only run the partitioning e.g. on the insertion of new entries, which can occur within a day/week/month or even a year. This means that some entries marked to be removed could stay in the database for a longer period than they should.

Decision

In order to keep the entries for a certain period of time, we introduce a new column in the database tables, e.g. deleted_at, which will contain the timestamp of the deletion. The deletion of the entities will be handled either by a cron job on the server level or a scheduled task in the backend.

Rationale

PSQL has no built-in time-based job handling feature, therefore it should be handled either on the server level or in the backend.

Implications

Notes

Related map create
Related map delete
Example of the deletion query:
- DELETE FROM plants WHERE deleted_at IS NOT NULL and deleted_at < NOW() - INTERVAL '1 month'

Search Plants

Problem

We want to provide a usable search for plants that goes beyond searching for substring in various plant names. Partial matches of the following fields should be returned.

Unique name
Common names
Edible uses

Constraints

Results should be fetched in a single query in order to utilize pagination.
Exact matches should be ranked high.
The users language preference should be taken into account when ranking.
Matches in names should have a higher rank than those in edible uses.
We don't want to add additional databases like Elasticsearch or Meilisearch.

Assumptions

Postgres will perform reasonable with these search queries.
Using postgres or even extension specific functions with diesel is possible and maintainable.
The plants table stays relatively small (it won't reach millions of rows).
The query entered in the search typically has 1-2 words with no more than 4 words.

Solutions

Postgres Full Text Search

https://www.postgresql.org/docs/current/textsearch.html

Postgres provides built in full text search functionality.

Pros:

Easy to use.
No additional extensions needed.

Cons:

No ability to match parts of compound words. E.g. Searching for "Kirsche" wouldn't return a row containing "Frühkirsche".
Built in ranking works by count the occurrences of matched words in a document.
Seems better suited for searching through large text documents.

Partial Match With String Distance

https://www.postgresql.org/docs/14/fuzzystrmatch.html#id-1.11.7.24.7

Here a match would be found with an ILIKE query and the results ranked by measuring the Levenshtein distance between the query string and the matched word in the column. This distance describes the number of character changes required to transform one string into the other. A language-preference based factor can be applied to the rank depending on the language of the matched column.

Pros:

Very precise matching with very few irrelevant results.
Computationally simple and fast.

Cons:

Wouldn't be able to catch typos.
May miss relevant results where only a part of the strings match. E.g. a search for "Frühkirsche" would not return "Spätkirsche".

Partial Match With String Similarity

https://www.postgresql.org/docs/current/pgtrgm.html#id-1.11.7.44.6

A match can be found by using the string similarity operator % from the pg_trgm extension. This similarity is calculated by counting the number of shared trigrams between the strings. Pairs that have a similarity above a certain threshold would be matched. A trigram is a sequence of three consecutive characters in a string. This similarity can further be used to calculate a ranking in a similar manner as described in string distance.

Pros:

Ability to handle spelling mistakes in the query string·
Loose matching mechanism returns related results. E.g. a search for "Frühkirsche" would also return "Spätkirsche".

Cons:

Can produce very many results for short query strings.
Computationally more expensive than other options. Can be alleviated by creating an index on the relevant columns. https://www.postgresql.org/docs/current/pgtrgm.html#id-1.11.7.44.8
Less useful for very long query strings as there will be fewer common trigrams.

Decision

Given the constrains and assumptions Partial Match with String Similarity (pg_trgm) seems to be the best option for us.

Rationale

As there is a relatively small number of rows and search terms performance isn't that much of an issue.
As of writing this pg_trgm executes almost instantly in a 'search as you type' fashion.

The ability to handle spelling mistakes and loose matches is also great for us as plant names can be somewhat complicated to spell.

Generally it is seems to fit best for our usecase. Something like elasticsearch could cover the usecase better, however it adds a lot of complexity.

Implications

The following points are difficult if not impossible to implement using PostgreSQL.
Before trying them it should be evaluated if a different database like elasticsearch might be a better fit for this usecase.

Other columns can be matched with extra syntax (e.g. environmental fit or ecological value).
- This can be quite difficult when parsing the query yourself as you would have to 'invent' a query language.
- As an example: amarena cherry water_requirement = dry might work as you know that water_requirement = dry those belong together.
- However: amarena cherry alternate_name = Pacific silver fir doesn't work as it isn't clear which parts of Pacific silver fir belong to alternate_name an which parts don't. This is a somewhat cherry picked example, but there might be other problem like that we have to consider.
- Apart from that it isn't simple to add new where clauses to a query as we would have to parse the users input and at the same time prevent SQL injections (which isn't trivial).
Search in hierarchy is difficult
Search accuracy (stop words, stemming, etc.)

Database

Notes

Sync

Problem

For better collaboration, the frontend must be kept up to date with the latest changes in the frontend.

Constraints

The changes must be sent immediate.
Events must be sent to thousands of clients.
It should be extensible to also include events of other use cases (changes in plant database or avoiding poll for Nextcloud chat)

Assumptions

We don't need to acknowledge sent events.
We don't need to know which events we missed (as frontend is read-only or database is locked when offline)

Solutions

Websockets

Websockets with a protocol like STOMP could be used.

Decision

We use server-sent events (SSE) with the observer pattern in the backend.

Rationale

Example is available and already tested with a thousand of clients.
This adds additional complexity on client and server side as we don't need a full-duplex communication.

Implications

N/A

Notes

@Bushuo creates a tracer bullet to check how it works.

Uuid

Problem

Due to their randomness UUIDs might be sub-optimal for database operations, see https://www.cybertec-postgresql.com/en/unexpected-downsides-of-uuid-keys-in-postgresql/

Constraints

Assumptions

we are actually hit by the problem
we cannot easily change the UUIDs later in production

Solutions

Use UUIDv7

https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html

Use ULIDs

https://github.com/ulid/spec

Decision

Not yet decided

Rationale

Implications

Notes

Development Setup

Prerequisites

If you want to develop on the backend, make sure you have enough RAM. When performing cargo build, we have experienced (on wsl) a usage of ~12GB.

Python
Rust
Javascript
- nvm
- node

Operating Systems

Windows 11
macOS 13.1 (Unix)

IDE

Visual Studio Code for both Frontend and Backend

Visual Studio Code Extensions

Frontend

Prettier ESLint for JavaScript/TypeScript linting and code formatting

Backend

rust-analyzer

Rust formatting can be achieved by adding the following to settings.json in VSCode after installing rust-analyzer:

  "[rust]": {
    "editor.defaultFormatter": "rust-lang.rust-analyzer",
    "editor.formatOnSave": true
  }

Package Managers

Frontend npm
Backend cargo

Installing Node + Npm

If you are using unix, macOS, and windows WSL, consider using nvm to manage your node environment:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
nvm install 20
nvm use 20

Or if you use the default macOS starting with Catalina shell zsh, try:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh)"

Installing Rust + Cargo

If you’re using Linux or macOS, open a terminal and enter the following command:

$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

This installs rust and cargo automatically on your machine. If you get linker errors, proceed by installing a C Compiler, which will typically include a linker.

To install our specific version of Rust, just run the following command:

rustup install 1.74

On Windows, go to https://www.rust-lang.org/tools/install and follow the instructions for installing Rust. At some point in the installation, you’ll receive a message explaining that you’ll also need the MSVC build tools for Visual Studio 2013 or later.

To acquire the build tools, you’ll need to install Visual Studio 2022. When asked which workloads to install, include:

Desktop Development with C++
The Windows 10 or 11 SDK
The English language pack component, along with any other language pack of your choosing

In case you don't prefer any of the previously mentioned installations methods, click here for alternatives.

Browsers

Chrome 108.0.5359
Firefox 108.0.2

Dependencies

If you want to install all necessary dependencies for development run following command in /workspaces/PermaplanT:

make install

Containers

We are also supporting a containerized setup(docker/podman). For more information checkout the README inside .devcontainer.

Guidelines

This folder contains general developer guidelines for PermaplanT. In a few cases they can be broken but such occurrences must be documented, ideally with code comments nearby.

REST

We exclusively use:

JSON or images as content.
GET to retrieve resources.
POST to submit new resources to the server.
PUT to fully update an existing resource (fails if it does not exist).
PATCH to update parts of an existing resource (fails if it does not exist).
DELETE to remove resources.

Both PUT and PATCH should be implemented idempotent. I.e., doing the same API calls again must be a NOP.

Endpoints

The endpoint paths use:

hierarchical structure
nouns instead of verbs
only plural (exception: config)
all endpoints need authorization (exception: config)
all paths below /api
layer-specific paths below /maps/<map_id>/layers/<name of layer>/ e.g. /maps/<map_id>/layers/plants/plantings

Parameters

Use singular if there is only one item, plural for collections.
Search should have its own endpoint and parameter should be name
Return values are called Page* if they support paging. We use the parameter page and per_page (type integer) for pagination.
Currently we don't use filtering or sorting.
If in doubt, leave it out: keep parameters minimal.

Versioning

The frontend is the only user, so we only need minimal API versioning. The frontend only need to know if a reload is needed.

Files

We use utility functions to access files in Nextcloud.

Documentation

Documentation of APIs is done via utopia:

utoipa::path must be present for every endpoint e.g. #[get(...)]
all possible responses should be documented
- specific 2xx codes, e.g., we use 201 Created for successful POST requests
- all ways client could behave wrongly¹ using 4xx error codes

¹ i.e., how the API could be wrongly used (preconditions not met etc.)

Example:

#[utoipa::path(
    context_path = "/api/maps",
    responses(
        (status = 200, description = "Fetch a map by id", body = MapDto)
    ),
)]

Security

All endpoints except of /api/config must use Keycloak's jsonwebtoken and indicate so using:

#[utoipa::path(
    security(
        ("oauth2" = [])
    )
)]

Backend Logging

The backend uses env_logger together with log as a logging framework.

env_logger allows to configure logging via the environment variable RUST_LOG.

Changing the Logging Level

To change the log level you can do one of the following:

Run the backend with e.g. RUST_LOG='backend=debug,actix_web=info' cargo run to change the log level of our code to debug
Change the variable RUST_LOG in the .env file

Log Messages

Use detailed logging messages for easy troubleshooting. It must be clear what should have happened and what actually happened.
Include relevant context, parameters, error codes etc.
Log only if actually needed. Exceptions: all calls of endpoints and SQL queries should be completely logged (level: debug).
Always use the lowest applicable logging level.

Log Levels

Available logging levels are:

error
Use for events disrupting normal operations.
warn
Apply for potentially harmful situations or undesirable yet operational states.
info
Use to monitor the essential flow of the application, capturing important operations like successful user authentications.
debug
Reserved for development or debugging; includes detailed updates, states of critical application points, or SQL queries.
trace
Use for granular logging, such as step-by-step function execution, to aid in complex issue diagnosis.

How to add Logging

To log you can simply call the macros in the log crate.

For example to log using the debug level:

log::debug!("This is my variable: {}", some_variable);

As you can see, it can be used in the same way as for example println!().

Log SQL queries

SQL queries can be converted to something that can be logged using debug_query.

let query = diesel::delete(seeds::table.find(id));
debug!("{}", debug_query::<Pg, _>(&query));
query.execute(conn).await

Backend

Nearly all guidelines are documented using rust-clippy, so this document is kept short.

Always derive Debug and Clone (but beware of deriving Copy).
Actions must be created in backend/src/model/dto/actions.rs.
We reuse the global http client like this: let server = HttpServer::new(move || { App::new() /*other initialization code*/ .app_data(http_client.clone()) }).
Read also about backend logging.

Code

For both frontend/backend:

avoid magic constants, prefer to use constant variables instead
avoid obviously inefficient code if more efficient solutions are available (please benchmark or ask in case of doubt)

Database

use all features from PostgreSQL or PostGIS and all their guidelines
use snake_case for everything except database keywords, which should be UPPERCASE
prefer enums over numbers, numbers over text
enums names should be singular
table names should be plural
prefer IDs over TEXT for plants
prefer TEXT over VARCHAR(n), don't use other variants
prefer UUID as primary keys, except for tables that are not subject to concurrent use (backend creates new items)
prefer BIGSEQUENCE over SEQUENCE except for users/maps where 2 billion is obviously enough

Documentation

This document gives guidelines for contributors concerning PermaplanT's documentation. This document takes preference to the actual situation. If you see documentation not according to this document, please create an issue. Alternatively, you can directly fix it with your next MR.

Note: It is always allowed to improve the documentation, in every MR, even if the documentation fix is completely unrelated. However, separate MRs are preferred and can potentially get merged sooner.

Target Groups

We write documentation only for contributors, i.e., a person who makes changes within PermaplanT's repository.

Every document must be clearly addressed to this target group.

Orientation

Each documentation should clearly be oriented to one of these three directions:

learning-oriented: First introduction is done via README.md and tutorials, they teach the fundamentals.
information-oriented: E.g. API docs are the references.
understanding-oriented: The doc/decisions explain the "Why?" something is done as it is done, i.e., the rationale.

Literature mentions also goal-oriented concepts, but we prefer learning-oriented approaches. E.g. of course you might have the goal to write a new plugin. But why not also learn about plugins while creating a new plugin?

Takeaway: Don't try to combine different orientations in one document, instead split your documentation up in e.g. a README.md (information), tutorial (learning) and decisions (understanding).

Criteria

PermaplanT's documentation must fulfill:

Always write what is, not what you would like to have except of decisions. Explanations must always refer to the current situation (as changed with your MR).
It is self-contained. It is not enough to link to some paper and an external page as explanation. All explanation must be within the repository, e.g., in case the external information goes away. This doesn't apply if the authoritative standard lives outside of PermaplanT. Then you would write, e.g., "The toml plugin implements this standard, with following extensions:". The extensions, however, again must be fully listed within our repository. Make sure to link to the correct version of the standard.
We use standard Markdown where possible, with only a few extensions:
- styled fenced blocks
- - [ ] option lists
- - <word>:<line break> description lists
The documentation should be as near to the code as possible.

Takeaway: Include full API and Markdown documentation of the current situation directly in your MRs.

Style

Sentences are short and written in one line. I.e. lines usually end with ., : or ;. Avoid line breaks in the middle of the sentence.
Use active and strong verbs early in your sentences. "We" refers to the community around the PermaplanT Initiative.
Use headings and lists to keep a clear structure in the text.
Use examples and images to emphasize important points, don't overuse emphasis in text (bold, etc.).
Spelling is American English.
It is consistent with our glossary.

Note: Please extend glossary as needed.

Completeness

In general the documentation does not need to be complete. In particular, we do not want repetition of implementation details as documentation. Prefer to write self-documenting code. Nevertheless, there are a few must-haves:

A README.md must be available for every module.
A man page (help/kdb-) must be available for every command (including external commands).
A tutorial must be present for every important concept.
Everything copied must be properly licensed.

Templates

In general we use arc42.org but we use specialized templates for:

decisions

How to write tests

Locator Guidelines

Before developing E2E tests make sure you have read the locator guidelines.

General rules

Be consistent and minimalistic.
- Don't use synonyms. Use the same vocabulary as Playwright (click, visible, etc.).
- Avoid using multiple different verbs for the same actions, keep your vocabulary small and precise. Use Playwrights vocabulary. This means to prefix methods with the actions from Playwright (e.g when calling xyz.click() from Playwright inside that method, name the method click_xyz() not a mix of press, click, push etc.)
- Don't indent more than one time.
- Don't make a complicated call stack higher than two from a page object.
Every test should be independent from other tests (concurrency).
Name inputs or objects you create SUT (System under Test) so they are clearly marked as test artifacts.

A typical workflow

The usual workflow consists of three steps:

(/features) write a feature with one or multiple scenarios.
(/pages) implement the page objects.
(/steps) create a function for each scenario step using the page objects.

Let us go over these steps in more detail.

Writing .feature files

Make sure to have a solid understanding about the Gherkin syntax, so you don't fall into common pitfalls. Usually the syntax is not very strict but poor Gherkin will cascade into the later processes of testing and make everything more complicated.

Here are some general guidelines for writing Gherkin.

We have decided to use "I" instead of the third person.

Implementing Page Objects

ALL tests are performed exclusively with page objects, where the selectors and functions are defined inside a class. If you are not familiar with the page object model look here if you are familiar with the page object model, still have a look : ). The page objects are all instantiated globally inside conftest.py and injected into the step functions as arguments. When using Playwright for Python we are interacting with Playwrights page class, which is basically representing a tab. This Playwright page class is then instantiated as a singleton and used globally across all OUR page objects to perform actions on the webapp. It is crucial to pay close attention what the side effects of OUR page object methods are as some methods will change the webpage and you will have to use a different page object after.

The Pagefactory does not exist yet due to implementation difficulty and for flexible design at the start. Just use the fixtures instead as they basically do the same.

Creating steps with pytest-bdd

When implementing the test steps you should ONLY be invoking methods of page objects to reach your goal. Implementing complex functionalities inside tests should be STRICTLY avoided and implemented into the corresponding page objects.

Following the testing strategy from PermaplanT:

Given should ARRANGE
When should ACT
Then should ASSERT

This will ensure the tests are simple and don't perform too much magic all over the place.

Parallelization

Pytest-xdist is used to parallelize the tests. This is done to reduce the pipeline time, since many tests could make this stage take a long time at the end. When developing tests always keep in mind that each scenario is running on a separate core and should not depend on results of other scenarios. A scenario outlet will also start each scenario with one core. Try to avoid too complex parallelization and we also probably don't need to assign and manage worker groups with additional xdist syntax.

Helpful tools

Playwright Test Generator

This is the fastest way to get some locators and see how Playwright would write the tests. This should under no circumstances be copy pasted and put into a test but rather help you write the page objects.

Launch it from the terminal and create code that you can later refactor into your page objects.

playwright codegen http://localhost:5173/

Pytest-bdd Test generator

pytest-bdd generate features/login_logout.feature > steps/test_some_feature.py

Only missing stuff:

pytest --generate-missing --feature features steps/

Frontend API Calls

These guidelines outline best practices for making API calls using React-Query within our project.

What is React-Query?

React-Query is a library that provides hooks and utilities for managing, caching, and synchronizing asynchronous and remote data in React applications.

Basic Concepts

When integrating React-Query for API calls, consider the following guidelines:

Query keys

Query keys are crucial for React-Query to manage caching and data fetching efficiently. They also play a crucial role in how queries get invalidated after a mutation.
Use meaningful and unique query keys to identify each API call.
Have a look at following guidelines: https://tanstack.com/query/v3/docs/framework/react/guides/query-keys and https://tkdodo.eu/blog/effective-react-query-keys

Example

const useUserData = (userId) => {
  return useQuery(["user", userId], fetchUserData);
};

Local Error handling

Errors can be handled locally by using isError flag from useQuery:

const UserProfile = () => {
  const { data, isError } = useQuery("userData", fetchUserData);

  if (isError) {
    // Render UI for error state
    return <div>Error fetching data</div>;
  }

  // Render UI for successful data fetch
  return <div>{data}</div>;
};

Global Error Callbacks

If a toast message should be shown use meta information for passing error message.
The error will be handled by the global onError function defined in @/config/react_query/index.ts.
Related blog post: https://tkdodo.eu/blog/breaking-react-querys-api-on-purpose#a-bad-api

const { data, isLoading } = useQuery(["files", path], {
  queryFn: () =>
    (webdav as WebDAVClient).getDirectoryContents("/remote.php/webdav/" + path),
  meta: {
    errorMessage: t("fileSelector:error"),
  },
});

Mutation

Use mutations for data modification operations (POST, PUT, DELETE).
Mutations automatically handle the asynchronous process, providing a clean and consistent way to update data.

Example

const addFile = useMutation({
    mutationFn: (file: FileOptions) => {
      return (webdav as WebDAVClient).putFileContents(
        WEBDAV_PATH + file.path + '/' + file.name,
        file.buffer,
      );
    },
    onError: () => {
      errorToastGrouped(t('uploadFile:upload_error'));
    },
    onSuccess: (data, variables, context) => {
      toast.success(variables.name + ' successfully uploaded!');
      if (onSuccess) {
        onSuccess(data, variables, context);
      }
    },
  });

Scalable Approach

The above examples are useful for understanding how react-query works and for one-off api calls that are just made from a single point in the code. A scalable approach is to define per feature a query-key factory:

const USER_KEYS = {
  _helpers: {
    all: [{ entity: "user" }] as const,
    details: () =>
      [{ ...USER_KEYS._helpers.all[0], scope: "details" }] as const,
  },
  detail: (userId: string) =>
    [{ ...USER_KEYS._helpers.details()[0], userId }] as const,
};

and to use it like this in queries:

const useUserData = (userId) => {
  return useQuery({
    queryKey: USER_KEYS.detail(userId), // use the query key for user detail
    queryFn: userDataQueryFn,
  });
};

function userDataQueryFn({
  queryKey,
}: QueryFunctionContext<ReturnType<USER_KEYS["detail"]>>) {
  const { userId } = queryKey; // type safe destructuring, makes sure query key and arguments do not diverge

  return fetchUserData(userId);
}

With the above example a user detail query key would have the following structure.

[
  {
    "entity": "user",
    "scope": "detail",
    "userId": 1
  }
]

Such a structure allows invalidation on different levels. For example invalidating all queries that concern the user entity, or all queries that concern the user details or a single user detail query.

A mutation that updates a single user resource on the backend, can then easily invalidate the respective query like so:

const useUpdateUserData(updateUserDto) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFunction: () => updateUserData(updateUserDto),
    onSuccess: () => queryClient.invalidateQueries(USER_KEYS.detail(updateUserDto.userId)), // invalidates all queries that match the query key
  })
}

Deep Dive (whole blog series)

https://tkdodo.eu/blog/practical-react-query

Creating a New Layer in Frontend

This document gives guidelines on how to implement a new layer in the frontend.

Folder Structure

Navigate to the layers directory in your project (features/map_planning/layers).
Create a new folder named after the type of layer you want to add (e.g., new_layer).

Add Necessary Files and Folders

Inside the "newLayer" folder:
- If your layer requires API interactions, create an api folder and place your .ts files in there or place them into the map_planning api folder depending on whether it's a special api that is part of the layer or it's just for initiating the layer in general.
- For React components or custom hooks specific to this layer, add a components or hooks folder.
- Create a main TypeScript file for the layer (e.g., NewLayer.tsx).
- Inside components create a NewLayerLeftToolbar.tsx and a NewLayerRightToolbar.tsx.
- Inside the newLayer folder create a file actions.ts.

Define the Layer Component

In NewLayer.tsx:
- Import Konva and other dependencies.
- Define a functional component that returns a Konva Layer.
In mapEditorHookApi.ts:
- Define a hook for your layer (e.g., useNewLayer.tsx).
- Add states (see next section) that need to be saved across components.
- Add an init function (e.g., initNewLayer) which is then defined inside the TrackedMapStore.ts.

Implement Layer Logic

Use hooks (starting with use in the name) and the global MapStore (tracked & untracked) to manage state and interactions.
Ensure proper interaction with other layers and elements.
In EditorMap.getToolbarContent replace the empty divs for left and right with the toolbars for your layer.
The NewLayerLeftToolbar.tsx should be used for manipulating attributes of the selected element in the map.
The NewLayerRightToolbar.tsx should be used to select elements to be placed/drawn on the map.
For selecting an element to be placed add a function to UntrackedMapStore.ts and a state to MapStoreTypes.ts.
For placing an element on the map create a class for creating the element inside actions.ts.
- This has to be done for every (tracked) action the user can take like deleting, moving and so on.
- In every action the following functions are needed:
  - entityIds: entity ids that are affected by this action
  - execute: commits the changes over the api
  - reverse: undoes the action
  - apply: applies the given tracked state
Use the actions within NewLayer.tsx in listeners or hooks.

Test Your Layer

Write tests for hooks (in the same folder as hooks) if feasible/useful (see plant/hooks) to verify functionality.
- Especially if side effects or wrong behaviour can not be easily seen in manual tests!

Frontend Keybindings

This document gives guidelines on how to implement keybindings in the frontend.

Keybinding Configuration

The files config/keybindings/keybindings_windows_linux and config/keybindings/keybindings_macos contains all keybindings that are used in the application and serves the following characteristics:

for all features add commonly-used and vim-like bindings
we generally try to provide several keybindings for the same functionality, to make the functionality easier accessible
there are different sections for keybindings:
- global: keybindings that are globally active
- Scopes for specific layers: Keybindings that are only active if the corresponding layer is active. These scopes should be named according to the layer name, postfixed with _layer.
- _just_for_documentation_: Keybindings that are only used for documentation purposes since the keybinding is hardcoded in the component. For example, the search field can be cleared by pressing the Escape key, which is typically a native browser action and should not be configurable in the keybindings file.
modifier keys are supported:
- Windows and Linux: Shift, Ctrl, Alt, Meta
- macOS: Shift, Ctrl, Opt, Cmd
- they can be used in combination with other keys by using the '+' sign (e.g. 'Alt+P', 'Shift+A')
multiple keybindings can be assigned to one action

Structure:

{
  "global": {
    "<<action_name>>": ["<<Key-Binding>>", "..."]
  },
  "base_layer": {
    "<<action_name>>": ["<<Key-Binding>>", "..."]
  },
  "plants_layer": {
    "exitPlantingMode": ["Escape"]
  },
  "_just_for_documentation_": {
    "clearSearch": ["Escape"]
  }
}

Keyhandling on Focused Elements

for components that provide keylisteners and are usually focused on use (e.g. input fields)
method:
1. add keybinding to json configuration for the corresponding action
2. bind a keyhandler to the component that should handle the key event if focused
3. retrieve the action name configured for the pressed shortcut using helper methods from config/keybindings/keybindings.ts
4. trigger the corresponding action
if actions of parent components shouldn't be triggered, event propagation must be stopped

Example:

    const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
      const action = getActionNameFromKeyEvent(<scope>, event);
      if(action === "doSomething"){
        doSomething();
        event.stopPropagation();
      }
    };

Keyhandling Independent of Focus

used if keylistener should be triggered independent of focused HTML element
method:
1. add keybinding to json configuration for the corresponding action
2. create action handlers that maps the action name to the corresponding function that should be triggered
3. use createKeyHandlersFromConfig helper method from config/keybindings/keybindings.ts to create map of shortcuts to action handlers according to config
4. use custom keybinding hook hooks/useKeyHandlers to bind keyhandlers to document or specific node

Example:

const keyHandlerActions: Record<string, () => void> = {
  exitPlantingMode: () => {
    exitPlantingMode();
  },
};

//use or custom hook to bind keyhandlers
useKeyHandlers(
  createKeyHandlersFromConfig("planting_layer", keyHandlerActions),
);

listener is active as long as the component where hook is used is rendered

Important Notes for Konva Key Handling

since keys cannot be bound directly on konva elements, keybinding have to check if the corresponding layer is active to avoid collisions
if keys should only be active if map is focused, handlers have to be bound to canvas section of the map component

Frontend Locators

These guidelines will help you write resilient and user-centric locators that can be utilized robustly in E2E tests. They are mostly inspired by Playwrights Documentation.

What are Locators

Frontend locators are essential elements in web development that enable developers and automated testing tools to identify and interact with specific elements on a web page.

The most popular locators are getByRole(), getByLabel() for user-centric and getByTestId() for more resilient tests.

Nevertheless not all cases can be solved with these 3 locators, so you might use other locators too. A quick overview of the most important locators.

getByRole

To make tests resilient, we recommend prioritizing user-facing attributes and explicit contracts such as page.getByRole()

Allows locating elements by their ARIA role, ARIA attributes and accessible name. This is semi resilient.

Example

const MyButtonComponent = () => {
  return (
    <div>
      <button role="button" id="myButton">
        Click Me
      </button>
    </div>
  );
};

getByLabel

Most form controls usually have dedicated labels that could be conveniently used to interact with the form. In this case, you can locate the control by its associated label using page.getByLabel().

Allows locating input elements by the text of the associated <label> or aria-labelledby element, or by the aria-label attribute. This is a reasonable alternative popular for input forms.

Example

const MyFormComponent = () => {
  return (
    <div>
      <label htmlFor="inputField">Enter your name:</label>
      <input type="text" id="inputField" />
      <button role="button" id="submitButton">
        Submit
      </button>
    </div>
  );
};

getByTestId (data-testid)

Testing by test ids is the most resilient way of testing as even if your text or role of the attribute changes the test will still pass. QA's and developers should define explicit test ids and query them with page.getByTestId(). However testing by test ids is not user facing. If the role or text value is important to you then consider using user facing locators such as role and text locators.

Locate elements by data-testid. The most resilient attribute.

Example

<SimpleFormInput
  id="file"
  labelText={t("baseLayerForm:image_path_field")}
  onChange={(e) => setPathInput(e.target.value)}
  value={pathInput}
  data-testid="baseBackgroundSelect"
/>

Data-testid Naming Convention

For naming data-testid's we have adapted the convention from BEM. We use double underscores to distinguish between Components and Elements e.g. search-input__search-icon where search-input is the component and search-icon the element.

getByText

We recommend using text locators to find non interactive elements like div, span, p, etc. For interactive elements like button, a, input, etc. use role locators.

Allows locating elements that contain a given text. This alternative should only be picked if the other three are not solving the case. It is not very resilient and can frequently break tests, therefore using a regex might be a good compromise.

There is no real example for this as this is basically the result of not doing anything specific.

Others

getByPlaceholder() to locate an input by placeholder.

<CreatableSelectMenu placeholder="Test" />

getByAltText() to locate an element, usually image, by its text alternative.
getByTitle() to locate an element by its title attribute.

Playwright suggested locators

These locators are from the official documentation of playwright. It shows which locators actionable elements usually should have.

text inputs: label
checkboxes: label
radio buttons: label
select options: label
mouse clicks: role or text
type characters: locator
keys and shortcuts: text or role
upload files and focus elements: label

User facing or resilient?

When choosing the right locator it is important to ask yourself one question. Do we want to test what the user perceives? If so, we can use roles and labels. If user-centricity is not so important on this element use data-testid. In case of doubt use data-testid.

Frontend UI & Usability

This guide should help improve the UI (User Interface) and usability of the PermaplanT web application going forward.
Its focus is:

on the one hand a mix of general UI and usability best practices and
on the other hand design suggestions tailored to PermaplanT.

Text

Size
- <h1> Headings : text-2xl
- <h2> Subheadings: text-xl
- <h3> Subheadings (currently not used/needed): text-lg
- Navigation items: text-lg
- Running text: text-sm
- Form fields and labels: text-sm
Family
- PermaplanT is using Tailwind's default cross-browser sans-serif stack everywhere. (If a different family is to be used in the future, extend the theme with a new theme.fontFamily section in our Tailwind config file tailwind.config.js.)
Alignment
- Always left align everything.
- Exceptions:
  - Modals: center headings
  - Guided tour: center highlighted actions
Spacing / margin
- <h1> Headings: mb-8
- <h2> Subheadings (and below): mb-2
- Cards (like on our Map overview): mb-4
- Form fields (like on the Seeds page): mb-8
- Labels of form fields: mb-2
Letter spacing
- Always go with the default value, i.e. tracking-normal. (In case letter spacing changes are considered in the future:
  - Headings: use negative values for the bigger headings h1-h3, i.e. tracking-tighter or tracking-tight
  - Running text: tracking-wide or tracking-wider)

Colors

PermaplanT uses following color palettes:

Neutral (PermaplanT: gray): dominant color of the design, e.g., used for background, text and labels.
Primary (PermaplanT: asparagus green): PermaplanT's main brand color, e.g. used for call-to-action buttons, checkmarks, highlighting focused form input fields, hovering over icons, highlighting active/enabled icons in the toolbox.
Secondary (PermaplanT: sea blue): PermaplanT's second brand color, e.g. used for highlighting selected plants on the map, currently focused icons, spinners, action-texts in the guided tour and bigger UI elements like the transparency bars to have some contrast to the primary color.
Tailwind's default color palette for red is e.g. used to render validation errors in forms, form field asterisks (text-red-500), buttons for destructive actions.

Only those color palettes should be used throughout the whole application. The colors are stored within the Tailwind CSS color definitions primary, secondary and neutral. They can be accessed like any other defined color in Tailwind CSS and can be appended with a number denoting the shade to be used.

Following shade suggestions should be used as a starting point for coloring new UI components: | location | light mode | dark mode | | :------------------ | :------------- | :------------ | | main color | 500 | 300 | | text on main | 50 | 700 | | alternative color | 200 | 600 | | text on alternative | 800 | 200 |

(Google's Material Design Guidelines contains more information on color palettes and their usage.)

Forms

Design

Cancel should be blue and on the left bottom.
Labels should be shown above edit fields.
Display a left aligned heading if the form is representing a whole page, e.g. PermaplanT's forms to create maps and seeds.
Add a capitalized label above each field.
Align labels to the left of their corresponding fields.
Always use the for HTML attribute (in React: htmlFor) to bind the label to the field.
Always use PermaplanT's SearchInput component to declare search fields instead of declaring them with type search.
Don't use the title attribute for any form fields (see https://inclusive-components.design/tooltips-toggletips/)
All form fields should have the same styling:
- border color: border-neutral-500 dark:border-neutral-400-dark
- border focus: focus:border-primary-500 dark:focus:border-primary-300
- border radius: rounded-lg
- padding: p-2.5
- placeholder: placeholder-neutral-300
- text: text-sm

Error Prevention

Validation errors are detected and shown by using the native input validation of HTML5.
Use the corresponding type of the input field, e.g. date for date fields, number for numerical-only inputs etc.
Mark required fields with an asterisk (see above for coloring)
Use HTML-native constraint attributes for input fields where appropriate, e.g. maxlength, required, step, etc.
Use short placeholder texts for input fields to show allowed values or further explain the intent of the input field.
Users should never be required to manually enter a metrical unit or a currency symbol. Instead, make the unit part of the input field itself or leave it out if it's clear from the context.
Submission to the backend should not happen until all fields are verified by the frontend logic.
In case of submissions on-the-fly (always except of pages that only consist of a form), the data should always be submitted with debouncing.
Double submissions should be correctly prevented (not via disabling buttons, as submission via enter or shortcuts still might be possible).

Consistency

Things with the same meaning should look and behave the same throughout the whole application. Users should never be uncertain if different words or icons mean the same thing, or different actions trigger the same process.

Examples:

Main Heading of a page is always defined by <h1> which must be the only one of its kind per page
Headings of all toolbars are always defined by <h2>
If textual links, e.g., the links in PermaplanT's navigation bar, need to be surrounded by space, always set their margin instead of padding.
Make call-to-action buttons look the same everywhere by using our SimpleButton component. Use Tailwind's classes to define the button's margin and width, if necessary due to layout or viewport.
We use *ToastGrouped with auto-close and default position (top-right) for information that should be shown as toast. Prefer to indicate errors more locally, if possible (like in forms).
Use the same application-specific terms as shown in the glossary everywhere when communicating to the user, e.g., always write PermaplanT.
A path with multiple points should be ended with a right mouse click, using similar text throughout the application in the status bar.

Icons

A tooltip on hovering must be displayed for every icon in PermaplanT's toolbox. The tooltip contains the icon's label (as concise as possible) and, if existing, the assigned shortcut in italics.
When active, i.e. currently activated/enabled, they must get a small highlighting through a visually stronger and more colorful appearance by using the design's primary colors.
When passive, i.e. currently not active/enabled, they must must appear in neutral colors/colorless.
When disabled, i.e. currently not clickable, they must be greyed-out, via decreasing their opacity.
The mouse cursor must be styled with the not-allowed CSS property.

Highlighting

Highlighting techniques:

Font weight:
- Bold text adds tolerable noise to the design and enables distinct highlighting in both short and long texts. It is the preferred highlighting technique to use. Nevertheless, use it sparingly.
- Italic text adds minimal noise to the design, but lacks in recognizability.
- Underlining adds most noise and compromises a text's legibility. It should not be used except for links.
Colors: primary and secondary colors of the design's color palette Use the secondary colour only for links.
Images: users generally remember images better than words

Wording

Messages shown to the user should strive to fulfill following criteria:

concise: the more text the less likely it will be read by the user
clear: straight to the message's essence
understandable for technical laymen: no status codes or technical terms
no exclamation marks: might come across as commanding
no uppercase words: might come across as shouting
detailed information should be hidden behind a read more link or a collapsed section
Headlines, Sub-headlines and Labels should be capitalized
Minimize hyphenation of words
English: American English
German: Neue Rechtschreibung, informal "du"
use plural to avoid gendering, i.e. use we/they, avoid he/she

Keybindings

ESC should do the equivalent to clicking X in the status bar
ESC should cancel current selections

Error Messages

In general, error messages often convey the impression that an application's stability is weak which, in consequence, leads to a declined user experience. Error messages should only be used if the user, without that information, would be badly surprised by the result of an action. Always prefer locally given visual indications to error messages.

Error messages should fulfill following criteria:

polite and neutral: do not directly or indirectly blame anyone and stay away from jokes
start the message with Sorry, ...
(German: "Entschuldigung, ...")
write personified, e.g., I could not ...
(German: "Ich konnte ... leider nicht ..."; "leider" might be omitted)
brief
specific to the problem
no technical terms and error codes
mention a reason for the problem and say probably if not totally sure about the problem (you verified that this must be the reason)
also offer possible solutions only, and only if, you are sure about them (you verified that this must be the solution)
use colors/formatting to highlight important passages (see above)
show via errorToastGrouped, for details see above in Consistency

E.g.: "Sorry, I cannot communicate with my server, there is probably some network problem or the server is down. Please retry later."

Z-Index

For a clean and maintainable layout, z-index should be used sparingly. Isolate z-index control to the root element of each component that needs overlapping elements. This creates staking contexts within components, preventing z-index conflicts across the application. If an element within a component doesn't require special z-index positioning, leave it to the default value of 'auto'.

List of z-index values currently present in the application, for future reference:

BottomStatusPanel (inner Component of BaseStage.tsx): 10
Tooltip in PlanningAttributeEditForm component: 20
Leaflet elements from OpenStreetMap (zoom +/- buttons, citation label on bottom right): 800 (note: pre-defined value coming from the external library used)
Navbar: 1001 (note: value chosen to be guaranteed "on top" of "Leaflet" elements)
TransparentBackground (usage in modals): 1010
ModalContainer (usage in modals): 1020
Toast notifications: 9999 (note: pre-defined value coming from the external library used)

Frontend

Development Setup

Use a Tailwind CSS linter (code plugin) if you write CSS
Use Storybook to develop components

Source Code Best Practices

We use Bulletproof React with following specialisations/exceptions:

We use camelCase in file names and identifiers.
We use absolute imports.
We use minimal number of packages: need to be noted in solutions or in a decision
Be thoughtful of memory consumption and runtime
Use debounce hook as in PlantingAttributeEditForm.tsx
Use react-query correctly, see our guidelines doc/guidelines/frontend-api-calls.md
Always validate form, use zod for more complicated validations
Wrap APIs using create*API in api folder
Be careful in writing hooks, especially when using useEffect
Error Handling https://tkdodo.eu/blog/breaking-react-querys-api-on-purpose#a-bad-api
Lists are called *List and items of such a list are called *ListItem, e.g., LayerList and LayerListItem for a list of layers

Route Naming Conventions

Follow RESTful conventions for route names.
Use descriptive, plural nouns for resource collections.
Use placeholders for dynamic segments in route names.

Examples

View: /resource
Edit: /resource/:id/edit
Create: /resource/create

Incorporate Accessibility Best Practices

Writing code that is highly accessible and easily testable should be a priority whenever possible. While it may not always be the primary focus, if you can achieve both goals simultaneously, it's worth pursuing that path. Additionally, many accessibility best practices are inherent in standard coding practices, such as using appropriate HTML elements like h1s, button tags, providing alt attributes for images and using appropriate ARIA roles and attributes.

i18n

Internationalization (i18n) is, except of a few _en/_de columns in the database, completely done in the frontend. We use react-i18next, which is a powerful framework to provide translation functionality and more.

Language Detection

On the initial page load the language gets detected from the browser settings. English is the fallback language if none of our currently supported languages (English, German) could be detected. This language is then persisted into local storage. The language switcher in the navigation bar also persists the chosen language to local storage. On any further page load this persisted language is used.

Structure

We use a feature-based translation approach.

The translations live in the /src/config/i18n directory together with the respective i18next configuration.
Each language has its own folder which holds all translations in files that are named like the features under /src/features. E.g. for the seeds feature there is a translation file in /src/config/i18n/seeds.json
The feature's translation file should be structured like this:

{
  "foo_component": {
    "title": "Foo",
    ...
  },
  "bar_component": {
    "title": "Bar",
    ...
  },
  "error_for_feature": "Sorry, ...",
  "common_key_inside_the_feature": "A mere commoner",
  ...
}

As we see in the example:

We use snake_case.
Hierarchy for components/sub-parts is recommended.
We use error_, title_, etc. prefixes (but you can also use hierarchy instead).
We don't abbreviate (button instead of btn).

Furthermore:

In case a translation does not fit into any feature there is an additional common namespace common.json defined. E.g. for general error messages.
Shared components like a button usually also want to render some text. In this case the text should be translated inside the respective feature where the button is used. E.g. the create seed button inside the seeds feature:

// seeds.json
{
  // CreateSeed component
  "create_seed": {
    "button_create_seed": "Create Seed"
  }
}

How To

If you want to translate a string, for example from the seeds feature in the CreateSeed component, follow this schema:

a whole translation key is structured like this <namespace>:<component>.<part>

function CreateSeed() {
  // load the translation namespaces 'seeds' and 'common'
  const { t } = useTranslation(["seeds", "common"]);

  // this is just an example
  const hasError = false;

  // wrap in <Suspense> to wait for the data fetching of useTranslation
  // use the t function to translate a key of namespace 'seeds' and 'common'
  return (
    <Suspense>
      {hasError ? (
        <div>{t("common:unknown_error")}</div>
      ) : (
        <button>{t("seeds:create_seed.btn_create_seed")}</button>
      )}
    </Suspense>
  );
}

Type Safe Keys

The translations are loaded from JSON modules to enable type safety. For this there is a special file @types/i18next.d.ts. Because it is impossible to type based on the chosen language, only the types of the fallback language en are defined.

Backend/Database

If multi-language entries are in the database or send by an endpoint, we use two fields ending with _en and _de.

Security

Authentication must happen in keycloak
- Decides who is member (only then you can create/edit any map)
- Also used for discovering users
Security of data must happen in the backend or in Nextcloud (for files)
Any modifications of elements or maps must be marked by:
- creation time (granularity in seconds)
- creation id (person who created)
- modification time (granularity in seconds)
- modification id (person who modified)
Only owners or collaborators are allowed to manipulate maps

Versioning

We increment the frontend version number on any release, which can happen:

when deployment on www.permaplant.net is needed
to be sure that newest version of dev.permaplant.net is present (e.g. for beta tests)
on any change in frontend/package.json

An updated frontend version number should lead to discarding all caches on clients.

Meetings

Meeting 2023-03-07

Protocolled by: Lukas

Attendees:

Samuel
Gabriel
Moritz
Giancarlo
Nursultan (audio-only)
Lukas
Markus
Yvonne

Buddies:

Lukas & Gabriel
Samuel & Nursultan
Giancarlo & Moritz

Agenda:

welcome ☺️
news about contact to your buddy
news from polyculture meeting
- Pavlo Ardanov
final touches for contribution guidelines https://github.com/ElektraInitiative/PermaplanT/pull/62
scope & date for first two milestones
in-person team event planning
qualifications/interests in team:
Postgis
Undo/redo
Architecture
Usability UI
Mockup
Google Spreadsheets
finishing & first discussions about assignment of use cases
Vertrag 📜
Projekte
review system with points
“Best PermaplanT Companion”-Awards
open tasks:
bugs for seed use case (split up)
plant db finishing touches (German etc.)
frontend tests&docu
decisions: state&architecture
closing

Meeting notes:

WELCOME
Task: Discussion with your buddy/buddies. Find similarities between you and your buddy/buddies.
- Colour Green: Walks in nature, houseplants, Spinach
- Letter A: in names, Android OS
- PermaplanT: Love for Open Source, Programming, Usability
- Contact to your Buddy
News from polyculture meeting
Discussion on Contribution Guidelines (#62)
- Shall we enforce having an issue for each PR?
in-person team event planning
Skill Check (bubble slide)
- technology
- design
- other skills
getting to know each other
- frontend/backend
- ui/db
- tea/coffee
- early bird/late worm
- smoothie/steam
- computer/plants
- soccer/yoga
Focus Groups
M1. Deadline: 19th March 2023
Use Cases
State Libraries (React): Comparison of Alternatives
- Recoil
- React Query
Gabriel: Backend PRs are blocking (e.g. Renaming)
CLOSING
(Personal) benefits of PermaplanT:
- growing more plants
- mapping of own garden
- technical challenges
- learning about cultivating plants (2x)
- thesis (3x)
- being part of an open source community (3x)
- putting something on my balcony

Meeting 2023-03-14

Protocolled by: Nursultan

Attendees:

Giancarlo (Best PermaplanT Companion KW11)
Samuel
Gabriel
Moritz
Nursultan
Lukas
Ramzan
Thorben Julian
Benjamin
Markus
Yvonne

Buddies:

Giancarlo & Moritz
Lukas & Gabriel
Samuel & Nursultan
Ramzan & Thorben & Benjamin

Tasks:

These tasks are to be done the day before the meeting

Add question/action points in agenda
Speak to your Buddy
Create a PR with README.md and research questions in private submissions repo
Collect points by reviewing other PRs
Sign Vertrag
Update Project
Nominate for “Best PermaplanT Companion”-Awards

Agenda:

09:00 welcome ☺️
- Ramzan
- Thorben Julian
- Benjamin
buddies
news
finishing M1:
- remaining RC-bugs for seed use case
- plant db finishing touches
- frontend tests&docu
other important topics (prep for M2):
- UX
- DB
- decisions: state&architecture
do more reviews of others PRs (goal: 2 reviews per PR)
new UI sketch (from Yvonne&Markus) with short feedback from you (details afterwards in UI focus team)
scope & date for M2
finishing & first discussions about assignment of use cases
Project Planning for next iteration
Yvonne found new database
10:00 closing & break
start UI focus team
in-detail discussion of UI sketch
mockup (directly with our framework?)
closing UI focus team

Meeting notes:

Persons

Nursultan's questions (link):
Samuel's questions
- Tight or loose integration with NC? Should the PermaplanT app work without NC?
- Integration of Nextcloud in Frontend or Backend client to NC communication:
  - web client <--> NC
  - web client <--> PROXY <--> NC
  - web client <--> backend <--> NC
- Where do we store user related information (DB or Nextcloud)?
  - credentials
  - location information
  - permissions/groups/roles
  - application data: ownership/membership of maps
- How do we retrieve relationships between plants? (Not included in current dataset)

Notes

welcome
discussed tasks for everybody
submit first version of your research questions in "submissions" repo
- shouldn't be perfect, just a first draft
do reviews of other PRs and collect points
discussed agenda
buddies + small creative task
end date of your thesis. thesis should be completed within one term but can be finished quicker
Moritz asked regarding git workflow in submissions repository: When should we create pull requests? When can we push directly to master?
- you can directly push to the master, e.g. for templates and other not-to-be-reviewed stuff
- open PR only for the parts that should be reviewed (this week at least the research question)
- entire thesis i.e. paper work should be finally in the "submissions" repo
focus groups
- small groups to discuss specific topics
- prefer github issues, meetings should be rather for clarifications
- also personal meetings are possible, if needed
adapt the meeting protocol template (Nursultan)
- status report vs questions
update authors file with your:
- expertises
- interest areas in the project
Markus and Yvonne presented a mockup for the plants layer
second milestone
- companions/antagonist data Benjamin
- first version of the canvas/map
- basic functionality of the map

UI Focus Group

hello
- Giancarlo: seed usecase
- Samuel: practical experience in data analysis software, experience with tailwindcss
- Thorben: practical experience in designing smaller business interfaces, mostly web design
- Moritz: full-stack
show similar features in Krita (tool buttons and layers)
Layers unintiutive? alternative? enable? Decision: we will use a group instead of top-level "alternatives" checkbox
to be tested: does a slider with double click work?
usage of mouseover text functionality
cluttered "drag and drop plants" -> also use groups here
date zoom functionality -> will be drawn last
buttons more standard?

Deliverables until the next meeting:

(additional to deliverables everyone needs to do)

Samuel
- NC decisions
- UI prototype
Gabriel
- decisions (API documentation, SQL queries)
- help seed milestone
Moritz
- seed milestone M1
- documentation of frontend
Giancarlo
- mockup of M2
- seeds
Nursultan
- varieties in plant database should be checked by Markus & Yvonne
- decisions/researches/architecture
Lukas
- CI/CD master deployment
Ramzan
- PostGIS
Thorben
- gamification use cases
- PostGIS
Benjamin
- get started with spreadsheet and Rust
- usecases

Progress Reports

Nursultan Progress Report

persistent undo when deleting a map/plant etc. #90
- scheduled deleting of a map/plant should be implemented either on the backend or server levels
- need to discuss ideas with the Lukas and Markus
confidence and strength of specific relations (e.g. buddy, dislike, ...) and attributes (e.g. wind, ...)
- Issue #88 / PR #89
- go through open conversations on the meeting
- task is completed on the structural level
- since genus/subfamily/family CSV files are not fixed yet, metatables are initially empty(maybe confusing for other team members?). In order to fill them right now, we need to manually add the data to the database with queries commented out in the migration file
- We also already have prefilled CSV files for genus/subfamily/family, which consist distinct values of the corresponding attributes. We can also use these files to fill the metatables.
undo-redo functionality of the map #91
- need a research on PostGIS
have a look at permapeople.org #102
- completed, you can find the results in the issue

Outlook:

To be done until 20.3.2023:

Review and correct research questions (in private submissions repo)
add TISS Entries (in private submissions repo)
- Matrikelnummer+Studium
- Beginndatum
- Erwartetes Ende (latest June)
- Titel (Deutsch+Englisch)
- Beschreibung/Abstract (Deutsch+Englisch)
- Schlagwörter (Deutsch+Englisch) (/ separated )
Speak to your Buddy
Update Project
Nominate for “Best PermaplanT Companion”-Awards

Meeting 2023-03-15 Gamification

Protocolled by: Markus

Attendees:

Markus
Yvonne
Pavlo
Thorben

Agenda:

Goals of the game(s)
Related work
Use cases
Brain storming for interface

Meeting notes:

Goals of the game(s)
- class room (learning) +1
- work in group
- behavior/choices of persons
- diversity +1
- intercropping?
model cases
calculate/evaluate performance:
- pest controls/attractive wild life/...
why game:
- put in parallel scenarios simultan
- lead to very different path way
- peer discussion
- peer experts help in assessment
- ranking (e.g. peer review happened)
Use cases
- known companions evaluated by growers (placement, constraints, preferences)
- growers have a list about 80 vegetables
- planning done by experts (maybe even same)
- work together
- output (harvest, measurement kits for soil, e.g. water measurements, taste)
- "citicen science"
- e.g. 10 growers with different combinations
- harvest basket/Erntekörbchen (to facilitate more diverse gardens and community work):
  - get good reviews in added plants
  - write good reviews (known companions and traits-based)
  - get good reviews when helping other people in their map
  - get good reviews of your own map
  - get new people apply for membership
  - good plant diversity, reward:
    - have the ingredients you need the whole year round (e.g. for a smoothie)
    - have at least 3 plants blooming simultaneously
    - plan a garden with given constraints (probably best doable if you can give others permissions to draw on alternative layers)
    - have all vegetables you need for a party at date X

Next meeting in around 3 weeks with use cases and mockups.

Meeting 2023-03-15 Polyculture Algorithm

Protocolled by: Benjamin

Attendees:

Benjamin Zinschitz
Markus Raab
Pavlo Ardanov
Uliana
Yvonne Markl

Preparations:

look at http://visegrad.permakultura.sk/polycultures/

Agenda:

Polyculture Basics
Presenting the pencil mockup
Modules of Tool
Introduction in Spreadsheets -> skipped
Taxonomy: Family/Genus
type of garden:
- forest garden
- ...
Test Data

Meeting notes:

Pavlo wanted to know if we want to build our own database or combine data from multiple external ones at run time. We will definitely go for the former.

Pavlo talked about the three modules that make up his tool.

Plant Requirements/Zones
Choose plants based on their environmental needs.
e.g. pH-value, soil density, lighting conditions, etc.
Known Plant Companions
Some plants work well with each other based on empirical evidence.
e.g. the aetheric oil emitted by one plant repels pests for another plant.
Trait-based approach
Two plants with different traits complement each other.

Approach one seems quite straight forward as long as we have sufficient data quality of requirements in our database and the user has good knowledge of her site.

We could populate the database with known companions for approach two. The question where to get this data from remains open for now.

There are hundreds of traits which can factor in for approach three. We need to find and define the ones with the most impact on plant growth speed, healthiness and crop yield while considering what data we have available. According to Pavlo the most important traits are shoot & root morphology while speed of growth and differences in point of harvest should also be considered.

We need to decide for which climate zone our algorithm should work.
For now we will settle for the middle european climate zone (cold winters, hot and dry summers).

There were also some ideas for the functionality of the app.

When plants are suggested the vegetation period could be considered as well.
We could pre-compute some some polyculture groups with a mix of approaches one and two. Considering the site details and preselected plants whole groups could be offered as suggestions.
In addition to suggesting what to plant we can suggest how to plant groups. Mixing seeds, placing them in rows or other shapes, etc.
Because people are creatures of habit we could suggest plants that are less used and have a high ecological value. E.g. attracts wildlife, bees, etc.

Meeting 2023-03-20 DB Kick-Off

Protocolled by: Nursultan

Attendees:

Nursultan
Moritz
Benjamin
Thorben
Ramzan
Paul
Markus
(everyone on the mailing list is welcomed)

Agenda:

welcome ☺️
goals:
- stable migrations
- maintenance
- performance
scraper/new columns:
- permapeople.org https://github.com/ElektraInitiative/PermaplanT/issues/102
- reinsaat.at https://github.com/ElektraInitiative/PermaplanT/issues/123
which important decisions do we need to make?
- plant relations: https://github.com/ElektraInitiative/PermaplanT/pull/89
- undo
- alternatives
- singular vs. plural
- ?
which tasks do we have?
who wants to work on which task?

Notes:

welcome and intoduction of the participants
postgis data should coordinate with real world
permapeople.org have more recent plants information than practicalplants
- suggested to sync the data with permapeople.org and our database bi-directionally
there will be a meeting with PostGIS expert for sure
discussion about the coordinate system of the map
- which coordinates are used in the database?
- which coordinates are used in the frontend by the canvas? e.g. zoom-in
5D coordinates: x, y, z, time and the alternatives
5D should be transformed into 2D
lazy loading of the map
- initial idea was to load only visible elements of the map on the startup
- however, for the offline mode we will need additional data e.g. plants information. not fixed yet
offline functionality is limited in respect to all the functionalities of PermaplanT

Resulting Tasks:

Nursultan:
- DB Design
- feasibility study
  - undo in DB
  - canvas zoom
  - what coordinates we have in the canvas? e.g. zoom-in
  - differences between databases
- permapeople.org https://github.com/ElektraInitiative/PermaplanT/issues/102
- reinsaat.at https://github.com/ElektraInitiative/PermaplanT/issues/123
Ramzan:
- guidelines
  - singular vs. plural
  - varchar vs. text
- layers/alternatives/time support in DB (together with Nursultan)
- continue researching/discovering PostGIS e.g. projection algorithms
Moritz:
- connect plants with seeds (together with Paul)
- handover of scraper tasks
Thorben:
- create ER/SQL for users and maps tables (coordinate with Samuel)
Benjamin:
- continue investigation in polyculture task

Meeting 2023-03-21

Protocolled by: Nursultan

Attendees:

Nursultan (Best PermaplanT Companion KW12)
Giancarlo (Best PermaplanT Companion KW11)
Paul (new)
Samuel
Gabriel
Moritz
Lukas
Ramzan
Benjamin
Markus
Yvonne

Cannot come:

(Thorben)

Buddies:

Giancarlo & Moritz
Lukas & Gabriel
Samuel & Nursultan
Ramzan & Thorben
Benjamin & Paul

Tasks:

These tasks are to be done ideally this week and at latest the day before the meeting

Add at least one question/action points in agenda
Speak to your Buddy
Create a PR with research questions in private submissions repo below your_name folder
Push your_name/TISS.txt file in private submissions repo with following entries (to be used in your application for the bachelor thesis in TISS)
- Matrikelnummer+Studium
- Beginndatum
- Erwartetes Ende (latest June)
- Titel (Deutsch+Englisch)
- Beschreibung/Abstract (Deutsch+Englisch)
- Schlagwörter (Deutsch+Englisch) (/ separated )
Speak to your Buddy
Update Project
Nominate for “Best PermaplanT Companion”-Awards KW12
Do at least 6 reviews of other PRs (main repo and submissions)
Finalize use cases (check what is open in #1)

Agenda:

09:00 welcome
- hello Paul ☺️
- celebrate Nursultan (Best PermaplanT Companion KW12)
activity
what is your case study? (use PermaplanT yourself)
SVG Tomato (NC Icons/Tomato.svg)
spoke with buddy? second buddy?
Project Planning for next iteration
enable GitHub+NC notifications
How many PRs did you review?
More active and faster in reviews
- add which PRs to review
- every PR should get 2 reviews
- look for "please review" labels
landing page https://github.com/ElektraInitiative/PermaplanT/pull/107
Milestones
- KW14: introduction&methods, implementation mostly done (eastern)
- KW17: related work, implementation finished
- KW20: abstract&conclusion, RQs answered
- KW23: submission of complete thesis, all tasks done (only fixing of unknown bugs remains)
- you can always do more
short news from our focus teams
- UI
- Polyculture
- Gamification
- DB
next meetings
- Thursday 9:00 Backend Kick-Off (Gabriel, Nursultan, Benjamin, Ramzan)
finalize use cases
assignment of one use cases
final round: "what is your case study?"
- Benjamin: linting&auto-formatting
- Gabriel: API documentation+ORM
- Giancarlo: finish seed use case
- Lukas: CI, (release)
- Moritz: finish seed use case
- Nursultan: feasibility study+architecture document
- Paul: Finish seed use case, Frontend
- Ramzan: Database Guidelines, Feasability, 1. QGis, 2. Projizieren, 3. Rastering
- Samuel: Landing Page, NC Decision Document

Outlook:

To be done within this week (24.03.2023):

Socratic questioning on your and other PRs (see socratic_questioning.md in submissions)
Create your own milestone plan and create PR to submissions
Look at one of the examples thesis in submissions
Add at least one question and a progress report in agenda (push to branch meeting_notes/28.03.2023)
Read all usecases, progress report which ones you find interesting
Speak to your Buddy: what will your case study be?
Update Project
Nominate for “Best PermaplanT Companion”-Awards KW13
Do at least 6 reviews of other PRs (main repo and submissions)

Questions and Help Needed:

Moritz

Discuss the usage of a documentation generator (like Doxygen, but for TS/Rust).
- Potential TS options:
  - API-Extractor
  - TypeDoc
- Potential Rust options:
  - rustdoc Note: seems to be the default/offial and only documentation method

Notes

welcome & warmup game
what is your case study? (use PermaplanT yourself)
- discuss with buddy
- collaborate
- how you can use PermaplanT? e.g. draw your garden
GitHub project
- should be up-to-date
- before the meeting update the status of your tasks
- discuss what is done during the meeting
archived old issues
sprint is always 1 week
"In progress" state
- only for issues that are currently worked on, not for issues that are planned to be worked on
- do not push too many issues to "in progress"
discussed tasks for the current sprint
feel free to tag somebody for a review (buddy, focus group, etc.)
- get involved in the PRs
- long-term: take a look at all PRs and find works related to you to give a review
- applies also for the "submissions" repo
- "please review" label
  - put it to your own PRs
  - once a week check for other PRs that have the label
milestones (calendar weeks described in agenda section)
news/updates from focus groups
next meetings(see agenda)
read all use cases and think about which one you want to work on
"Submissions" repo:
- socratic questioning
- do at least 2 reviews
- as a reviewer ask yourself socratic questions

Progress Reports:

Focus Group 'Gamification'

We defined the primary goals of the game aspect of PermaplanT (increasing positive gardening behaviour, encouraging collaboration on maps, providing a fun environment for class room learning).
We identified a usage scenario in citizen science: multiple growers, potentially working with experts, working together to evaluate and optimize known companions and their performance through a serious game type of parallel simulations and real-life analysis of the results.
We brainstormed a list of potential use cases around this citizen science scenario and the idea of collaboration on a shared map to help lesser experienced gardeners with their design through various forms of reviews.

Focus Group 'Polyculture'

We are developing the app for the middle european climate zone.
We have to define plant traits we want to focus on for trait based matching.
We need to find high quality data on plant traits and known companions.

Nursultan

persistent undo when deleting a map/plant etc. #90
- ready from my side and waiting of Lukas to complete the decision with exact solution for cron jobs
confidence and strength of specific relations (e.g. buddy, dislike, ...) and attributes (e.g. wind, ...) #88
- ready for review
- suggestion from Benjamin. detailed explanation and example queries needed
undo-redo functionality of the map #91
- research is in progress
import of permapeople.org data #102
- waiting for the data, either CSV or API keys
scrape reinsaat.at #103
- planned for this week

Meeting 2023-03-23 Backend Kick-Off

Protocolled by: Markus

Attendees:

Gabriel
Nursultan
Benjamin
Ramzan
(everyone on the mailing list is welcomed)

Agenda:

welcome ☺️
architecture:
- quality goals:
  1. stability
  2. maintenance
  3. performance
  4. privacy
- which modules do we have?
  - modules ~ endpoints, so it is map, users, ...
- where to add which code, e.g.:
  - polyculture algorithms -> subfolder in services (documentation will be written)
  - switching of layer/time -> parameters to endpoint
  - session handling -> nextcloud (OAuth client lib), token only in browser, not in backend or DB, open decision: best Rust OAuth Client (https://auth0.com/blog/build-an-api-in-rust-with-jwt-authentication-using-actix-web/)
  - transaction handling -> not needed
  - threading -> tokio
  - regular tasks (see decision below) -> Rust/tokio if easy, otherwise cronjob
  - validation -> done by diesel
  - reporting/monitoring tool
- solution strategy?
  - description of 3 layers
  - types/structs
  - diesel/rust intro in docs(Gabriel)
  - be stateless (all state in DB)
documentation:
1. mdBook (general intro)
2. API documentation (swagger?)
3. code documentation of backend
4. code documentation of frontend
to work with DB -> Diesel must be learned
which decisions do we need to make?
- API documentation
  - https://github.com/ElektraInitiative/PermaplanT/pull/101
  - typescript generation of openapi?
- DB documentation
  - https://github.com/ElektraInitiative/PermaplanT/issues/97 -> yes, we document the structs
  - what about SQL queries?
  - open decision: best Rust OAuth Client/Server
- regular tasks https://github.com/ElektraInitiative/PermaplanT/pull/130
which tasks do we have?
- logging decision
- extend pre-commit hook for backend (Benjamin)
- cargo watch (Gabriel)
who wants to work on which task?
Gabriel: mdBook, API docu
Benjamin: pre-commit hook, review mdBook, API frontend
Nursultan: documenting structs
Ramzan: Diesel Postgis, check how to document algorithm

Meeting 2023-03-28

Protocolled by: Nursultan

Attendees:

Benjamin (Best PermaplanT Companion KW13)
Nursultan (Best PermaplanT Companion KW12)
Giancarlo (Best PermaplanT Companion KW11)
Paul
Samuel
Gabriel
Moritz
Lukas
Ramzan
Thorben
Markus
Yvonne

Buddies:

Giancarlo & Moritz
Lukas & Gabriel
Samuel & Nursultan
Ramzan & Thorben
Benjamin & Paul

Task for Everyone

To be done within this week (24.03.2023):

Socratic questioning on your and as review on other PRs (see socratic_questioning.md in submissions)
Create your own milestone plan and create PR in submissions
Look at one of the examples thesis in submissions
Add at least one question and a progress report in agenda (push to branch meeting_notes/28.03.2023)
Read all usecases, progress report which ones you find interesting
Speak to your Buddy: what will your case study be?
Update Project
Nominate for “Best PermaplanT Companion”-Awards KW13
Do at least 6 reviews of other PRs (main repo and submissions)

Individual Tasks

Benjamin: use cases, linting&auto-formatting
Gabriel: API documentation+ORM
Giancarlo: finish seed use case
Lukas: CI, (release)
Moritz: finish seed use case
Nursultan: feasibility study+architecture document
Paul: Finish seed use case, Frontend
Ramzan: use cases, Database Guidelines, Feasability, 1. QGis, 2. Projizieren, 3. Rastering
Samuel: Landing Page, NC Decision Document
Thorben: use cases

Individual Tasks:

Benjamin: use cases, Pavlo
Gabriel: ORM decision, mdBook, build book
Giancarlo: Right Toolbar Mockup, layer
Lukas: Backend, URL, Frontend, Release
Moritz: Plant DB Integration, Backend Search, Cleaning up migration?
Nursultan: feasibility study+architecture document, check 10.000 elements, documentation
Paul: (Decision) Documentation Frontend, plant search (ranking), decision about full text search
Ramzan: use cases, Database Guidelines, Feasability, 1. QGis, 2. Projizieren, 3. Rastering
Samuel: Landing Page, Login Decision
Thorben: use cases, DB, ER Diagram

Agenda

09:00 welcome
Questions:
- buddy talk: what is your case study? (use PermaplanT yourself)
- GitHub+NC notifications enabled?
- How many PRs did you review?
- Interesting usecases?
In the future I see PermaplanT as ...
Project: Planning for next iteration
English:
- hyphen: up-to-date topic, highly-interactive app, vs. the app is highly interactive
- terms always the same (Glossary!)
- when writing, look up grammar rules etc.
- for verbs search for synonyms
getting better meeting notes
- always push to agenda what affects others (decisions, documentation, hooks, ...)
Tips for your thesis:
- Forschungstagebuch
- speed
- look at other thesis
- identify glossary terms with italics
- implementation details, make it shorter
- lessons learned are nice
- evaluation is must-have (how do we answer RQ. only results, without any opinion)
working together
- common components (SimpleButton improvement PR)
- benchmark setups
- code
- minimize work on thesis
technicalities:
- PRs with generic issues (use cases #1, decisions #2), don't need extra issues just for the PR
- make sure PRs have README.md (short description in GitHub)
- branch names see .github/CONTRIBUTING.md
- merging policy: own PRs should not be merged by yourself, others are okay if you are sure it is okay and it solves a problem for you (e.g. fixes builds).
paper
- how to write methodology
- what is important for RQs
outcome of backend meeting:
- we want to use Swagger
- decisions: prefer to simply push and consider all possible solutions even if it is obvious
assignment of one use cases
2nd milestone
- we should be able to plant plants

Frontend Meeting

Starts 15:30:

SVG (Tomato)
- check: svg on Konva
- Tomato_vector_transparent_background.kra
common components
- document in storybook
- https://tailblocks.cc/
tailwind configuration
mockup
- no description for layer buttons
- drag and drop for reordering the layers
- arrow for collapsing group
- add vertical dropdown for deleting
next steps:
- Giancarlo: svg on Konva, mockup
- Samuel: Color Schema, landing page
- Giancarlo: news
- Moritz: time line
- Samuel: slogan, UI plant use case
- corp. design
  - Yvonne: logo
  - Thorben: prim+sec color, 9-10 shades
  - Giancarlo: margins
  - Paul: section heading, shadows, layout improvement
next meeting: Friday 9:00

Progress Reports

milestones.md is in submissions repo
Samuel
- added env file with API_URL to frontend
- defined color structure in tailwind
- implemented landing page suggestions and dark mode
- stuck at accessing values from tailwind configuration (typescript errors)
Moritz
- seeds entry is almost done
- only thing that is that is missing is the integration of the scraped data
Benjamin
- Wrote the last remaining polyculture use cases.
- Set up pre commit hooks for the whole project.
- Add front end commands for the check stage of the CI pipeline.
- Get in touch with Pavlo to get more info on plant relation data.
- Work on a sketch for the database schema for representing plant relationships.

Questions

Samuel
- When are PRs merged?
- How to avoid duplicate effort? E.g. I am working on simple components that I need for my feature other people might need similar components for different feature. Should we create smaller PRs that get merged fast? E.g. SimpleButton improvement PR
Moritz
- Is there already a standard format for branch names and commit messages?
Benjamin
- Is the current state of the database schema on master fixed or subject to change?

Outlook

Extra Meetings:

Today 15:30: Frontend
Thursday 9:00: Polyculture

To be done till 31.3.2023:

finalize use cases
Read all decisions, progress report which ones you agree
start decisions #2
write Forschungstagebuch in submissions repo (longer progress report)
Add at least one question and a very short progress report, relevant for others (e.g. common components, decisions, ...), in agenda (push to branch meeting_notes/04.04.2023)
Speak to your Buddy about decisions
Update Project
Nominate for “Best PermaplanT Companion”-Awards KW14
Do at least 8 reviews of other PRs in this week (main repo and submissions)
Screen PermaplanT for the benefit that you personally want to achieve for your case study. Check, if your needs are met.
thesis: write methodology

Meeting 2023-03-30 - Polyculture

Protocolled by: Benjamin

Attendees:

Benjamin
Pavlo
Uliana
Markus
Yvonne

Agenda

09:00 Hello
Which database (columns) are best?
Grouping algorithms
Taxonomy
Test Data
Participation of Uliana
Tasks

Discussions

What kind of plants do we want to address?

Only vegetable and leafy green crops or more?
The database contains many different plants, including trees, all available for a planner.
For companions/antagonists, however, we focus on garden vegetables.
Diversity and ecological value plants should be included as well.

What databases to use?

We started scraping practicalplants.org and now integrate the data from permapeople.org. They are close to what Plants for a future provides except for plant relationships.
Plants for a future is a popular one.
- Will they allow us to use them?
- It's constantly updating, how can this be reflected?
  - We want to get daily updates via their API.
- They already sent us API keys. The current concept is: we update their wiki directly and then receive updates. We should arrange a meeting with them to talk about this.
Natural plant database (American) has more extensive data on relationships.
There are more important ones for polycultures (primary traits).

Which traits to use?

When these are defined we can take a look at which databases we can use.
- Examples are
  - Plant physiology
  - Growing period
  - ...
Yvonne has already done an investigation of databases. That's why permapeople.org was chosen so far. But some things are missing in there (e.g. relationships and seeds). Quality check hasn't been done thoroughly.

For relationships, we would like to have a confidence score.

We could also take relationship data from multiple sources and grade by this. How many databases say the same. Are there any contradictions?
Pavlo's concern is that a computer program would be more objective and efficient in the long term. Markus's concern is that scraping would be a big effort with little long-term benefits (scraping would need to be redone in future). Therefore we concluded the work will be done manually by Uliana. To keep the work at an acceptable level, we only include common vegetables on higher taxonomical ranks. As far as we know, this is novel, as other databases don't define relationships on higher taxonomical ranks.
Plants for a future and Natural capital plant database have relationship info readily available in spreadsheet format. We can probably use the info if we don't use any of relationship details.

Decisions

Uliana will start research on plant relationships.
First the quality of the following datasources has to be assessed.
Then a collection of relationships in the following format is created.
You can find the document here.
The left and right side of a relationship are plants where the order doesn't make a difference.
E.g. the relationship A companion B is identical to B companion A so only one of them should be added.
- Left side
  - Common name
  - Variety
  - Species
  - Genus
  - Subfamily
  - Family
  - Taxonomic rank
    - Variety
    - Species
    - Genus
    - Subfamily
    - Family
- Right side
  - See Left side
- Confidence
  - low
  - medium
  - high
  - approved
- Relationship type
  - companion
  - antagonist
  - neutral
- Notes
- Sources

Meeting 2023-03-31

Protocolled by: Moritz

Attendees:

Giancarlo (Best PermaplanT Companion KW11)
Paul
Samuel
Moritz
Thorben

Agenda

09:00 Hello
SVG (Tomato)
- check: svg on Konva
- Tomato_vector_transparent_background.kra
i18n (German/English) -> we use react i18next with static keys
common components
- document in storybook
- https://tailblocks.cc/
tailwind configuration
mockup
- no description for layer buttons
- drag and drop for reordering the layers
- arrow for collapsing group
- add vertical dropdown for deleting
next steps (old meeting):
- Giancarlo: svg on Konva, mockup
- Samuel: Color Schema, landing page
- Giancarlo: news
- Moritz: time line
- Samuel: slogan, UI plant use case
- corp. design
  - Yvonne: logo
  - Thorben: prim+sec color, 9-10 shades
  - Giancarlo: margins
  - Paul: section heading, shadows, layout improvement
next steps:
- Moritz: review
- Paul: translation
- Samuel: typewriter
- Thorben: colors

Meeting 2023-04-04

Protocolled by: Nursultan

Attendees

Samuel (Best PermaplanT Companion KW14)
Benjamin (Best PermaplanT Companion KW13)
Nursultan (Best PermaplanT Companion KW12)
Paul
Gabriel
Moritz
Lukas
Ramzan
Thorben
Markus
Yvonne

Could not come:

Giancarlo (Best PermaplanT Companion KW11)

Buddies

Giancarlo & Moritz
Lukas & Gabriel
Samuel & Nursultan
Ramzan & Thorben
Benjamin & Paul

Tasks for Everyone

To be done within this week KW13 (31.03.2023):

Finalize use cases
Read all decisions, progress report which ones you agree
Start decisions #2
Write Forschungstagebuch in submissions repo (longer progress report)
Add at least one question and a very short progress report, relevant for others (e.g. common components, decisions, ...), in agenda (push to branch meeting_notes/04.04.2023)
Speak to your Buddy about decisions
Update Project
Nominate for “Best PermaplanT Companion”-Awards KW14
Do at least 8 reviews of other PRs in this week (main repo and submissions)
Screen PermaplanT for the benefit that you personally want to achieve for your case study. Check, if your needs are met.
Thesis: write methodology

Individual Tasks

To be done within this week KW13 (31.03.2023):

Yvonne: Logo, Drawings, Testing Seed entries
Markus: landing page
Benjamin: plants relationship table finalized, use cases, squash migration
Gabriel: ORM implement, mdBook (with deployment), end points
Giancarlo: Sidebar Mockup, Implement drawing layer, Konva features, Improve Landing Page (add news)
Lukas: Frontend, Release Deployment, Import Seeds
Moritz: Seed Issues, Timeline
Nursultan: scraping, decisions, architecture, thesis study+architecture
Paul: translation for frontend, Documentation Frontend
Ramzan: use cases, Database Guidelines, SQL code examples Feasability, 1. QGis, 2. Projizieren, 3. Rastering
Samuel: Readd Map&Gallery, Login Decision, UI for plant use case (right toolbar), use cases
Thorben: use cases, DB/ER Diagram, Mockups

Agenda

09:00 welcome - Best PermaplanT Companion KW14: Samuel
Questions: - buddy talk: decisions - Interesting decisions? - How many PRs did you review?
Galgenmännchen
Project: Planning for next iteration
Responsibility on finishing own tasks and telling me if you cannot do it in time (TISS)
Terminology: - FLOSS - project vs. initiative - enumerate/itemize (consistent style!)
technicalities: - weekly merge PRs in submissions yourself (and create new ones) - adding preliminary pdfs for reviews can be useful (if you want comments on the pdf) - create new PRs for new content (both submissions+main repository) - images in nextcloud - please don't start discussions in (big) PRs
Thesis: - text structure: - theorems for RQs (restate via restatable etc.) - short sentences, verb early, use "we" - capitalization of headers - everything is understandable when reading from begin to end - without forward references - terms explained when used first - scientific structure: - observations and opinions clearly separated - connected with related work
outcome of frontend meeting - document components in storybook - modern, simple style with some chaotic elements - we use react i18next with static keys
outcome of polyculture meeting - manual creation of companions with certainty
M1 finish remaining tasks
M2 assignment - use cases - UI components
next meetings - DB - frontend - milestone finish?
pre-commit now active
- you need to fix linting errors in files you change
- you need to manually remove husky hook

Progress Reports

Please push progress reports in items below:

Paul: Finished TypeDoc/Storybook setup with newly released Storybook v7. Works way better than v6. I am confident for a PR now.
Thorben: Worked out color themes for the frontend together with Samuel and applied them to the UI components.
Gabriel: Status Code Bugfix, ORM decision (waiting for response), mdBook (WIP)
Benjamin: Meeting on how to gather plant relationship data, Get pre-commit hooks merged

Questions

Please push questions in items below:

Thorben

How do we want to persist the selectable elements of the different layers? One table per layer or one general table with differentiation through an element type property?
Participation on other peoples use cases that are not merged: add comment on PR or directly push to it? Or open new PR based on the initial PR's branch?

Decisions

Please push Progress in decisions, or other important changes devs should know, in items below:

Outlook

Vote for next focus group meetings until 4.4.2023: https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/12

To be done within next week KW14 (7.4.2023):

Update doc/authors.md to reflect what you already worked on
Add small picture of your head to Nextcloud (for landing page)
Test inserting seeds and report here
- Write decisions #2
- Read and update PermplanT's glossary
- Write Forschungstagebuch in submissions repo (longer progress report)
- Add at least one question and a very short progress report, relevant for others (e.g. common components, decisions, ...), in agenda (push to branch meeting_notes/11.04.2023)
- Update Project
- Nominate for “Best PermaplanT Companion”-Awards KW15
- Do at least 8 reviews of other PRs in this week (main repo and submissions)
- Speak to your Buddy about glossary, what is missing, what could be extended?
- Thesis: write Glossary&Goals (submission)
- (Optional) Add review/correction/proof-read metadata for every paragraph in thesis, see unterlagen/paragraph_metadata.md
- (Optional) Apply spelling.sed and checks to your thesis (see unterlagen)

Meeting 2023-04-07 DB

Protocolled by: Nursultan

Attendees

Nursultan
Moritz
Benjamin
Thorben
Ramzan
Paul
Markus
Luciano
Yvonne
(everyone on the mailing list is welcomed)

Preparations

given all the use cases, how should the tables for a map look like?
think about how we do the plants hierarchy (that plants from lower ranks inherit attributes from higher ranks, e.g. the specific Tomato https://www.reinsaat.at/shop/DE/tomaten_paradeiser/cocktailtomate/anabelle/ should contain all the data the general Tomato https://permapeople.org/plants/solanum-lycopersicum-tomato has, but without duplicating this data, see also https://github.com/ElektraInitiative/PermaplanT/blob/master/doc/decisions/database_structure.md for current status

Please make a sketch or similar of the tables.

Furthermore, following individual tasks as preparation:

Moritz: focus on question 2. of above
Nursultan: results of feasibility (which data of canvas needs to be stored in DB etc.)
Benjamin: look at how we do the plants hierarchy (that plants from lower ranks inherit what higher ranks have)
Ramzan: Which PostGIS datatypes will we use for 2D/3D points? Focus on question 1. of above
Thorben: ER/SQL for users and maps
Paul: how to sync map data for offline use

Previous Tasks

Nursultan:
- DB Design
- feasibility study
  - undo in DB
  - canvas zoom
  - what coordinates we have in the canvas? e.g. zoom-in
  - differences between databases
- permapeople.org https://github.com/ElektraInitiative/PermaplanT/issues/102
- reinsaat.at https://github.com/ElektraInitiative/PermaplanT/issues/123
Ramzan:
- guidelines
  - singular vs. plural
  - varchar vs. text
- layers/alternatives/time support in DB (together with Nursultan)
- continue researching/discovering PostGIS e.g. projection algorithms
Moritz:
- connect plants with seeds (together with Paul)
- handover of scraper tasks
Thorben:
- create ER/SQL for users and maps tables (coordinate with Samuel)
Benjamin:
- continue investigation in polyculture task

New Tasks

Yvonne: check if latin name is unique
Benjamin: plant hierachy, relationship
Moritz: latin_name rename
Nursultan: plant DB names i.e. scrapers
Paul:
Ramzan: rest DB
Thorben: rest DB

Agenda

14:00 start
welcome ☺️
goals:
- stable migrations
- maintenance
- performance
DB Design
scraper/new columns:
- permapeople.org https://github.com/ElektraInitiative/PermaplanT/issues/102
- reinsaat.at https://github.com/ElektraInitiative/PermaplanT/issues/123
which important decisions do we need to make?
- plant relations: https://github.com/ElektraInitiative/PermaplanT/pull/89
- undo
- alternatives
- singular vs. plural
- ?
who wants to work on which task?

Notes

Thorben presented the map
- re-check the requirements
coordinates in the database
- can use different coordinate systems. but costly
- kepler.gl can use lang/lat coordinate systems
- LeafletJS
- KonvaJS
cartesian vs lang/lat coordinates
balance between separate tables for each canvas object in the database vs. one table for the whole map as a stringified JSON
PostGIS can store raster information in the database
- user can brush to draw raster areas

Meeting 2023-04-07 Frontend

Protocolled by: Paul

Attendees

Giancarlo
Paul
Samuel
Moritz
Thorben
(everyone on the mailing list is welcomed)

Previous Tasks

Moritz: review
Paul: translation
Samuel: typewriter
Thorben: colors

Agenda

09:00 Start
SVG (Tomato)
- check: svg on Konva
- Tomato_vector_transparent_background.kra
i18n (German/English) -> we use react i18next with static keys
common components
- document in storybook
- https://tailblocks.cc/
tailwind configuration
mockup
- no description for layer buttons
- drag and drop for reordering the layers
- arrow for collapsing group
- add vertical dropdown for deleting
landing page https://github.com/ElektraInitiative/PermaplanT/pull/226
layers/sidebar prototype
timeline mockups https://github.com/ElektraInitiative/PermaplanT/pull/238
drawing layer https://github.com/ElektraInitiative/PermaplanT/pull/215
seed entry current status https://github.com/ElektraInitiative/PermaplanT/issues/209

Meeting Notes

translation
- it is hard to remember to keep the file structure in the language the same as the features:
  - maybe colocate the json to the component -> hard to implement
- language switcher as a dropdown
landing page https://github.com/ElektraInitiative/PermaplanT/pull/226
- logo and slogan should use the same colors
- legal issue, should the map be loaded immediatly
- clicking on the radio button is hard -> click on the whole row to select
- the slogan grows to both the left and the right -> Make it left aligned with fixed width layers/sidebar prototype
- transparency slider is not html 5 but from scratch -> look into usability
- the seperator between the layers and groups/search should also be draggable/resizable
- tooltips for the eye symbol and enable checkbox instead of labels
- for alternatives, a caret to expand
- buttons on the top right would be too small for touchscreens
- four groups should be hidden if search is pressed
timeline mockups https://github.com/ElektraInitiative/PermaplanT/pull/238
- should custom events be in the timeline as a separate view -> no, only addition and removal
- only visualize changes that actually happen on the map, addition/removal by the user
- is this too complex to implelement -> look for existing solutions
- simplifications we discussed
  - do not show individual events (color or number should indicate the amount of change)
  - only three steps of granularity, maybe even with a button group
drawing layer https://github.com/ElektraInitiative/PermaplanT/pull/215
- how are we structuring the layer code -> each layer should live under a layers folder in map_planning
- shared features like plat_search should have their own feature folder
seed entry current status https://github.com/ElektraInitiative/PermaplanT/issues/209
- edit and removal of seeds

Next step

moritz: seed finished, check ready-made solutions for timeline? create timeline decision
Giancarlo: seed overview (edit, delete, ...), code structure documentation
Paul: seed fix, i18n
Samuel: typewriter, toolbar improvements, pricing selection (add to email body)
Thorben: leaf picture color, blue color consistency, imprint, pricing

Meeting 2023-04-11

Protocolled by: Nursultan

Attendees

Moritz (Best PermaplanT Companion KW15)
Samuel (Best PermaplanT Companion KW14)
Benjamin (Best PermaplanT Companion KW13)
Nursultan (Best PermaplanT Companion KW12)
Giancarlo (Best PermaplanT Companion KW11)
Paul
Gabriel
Lukas
Ramzan
Thorben
Markus
Yvonne

Buddies

Giancarlo & Moritz
Lukas & Gabriel
Samuel & Nursultan
Ramzan & Thorben
Benjamin & Paul

Tasks for Everyone

To be done within next week KW14 (7.4.2023):

Update doc/authors.md to reflect what you already worked on
Add small picture of your head to Nextcloud in Public/Avatars (80x80 for landing page)
Test inserting seeds and report here
Write decisions #2
Read and update PermplanT's glossary
Write Forschungstagebuch in submissions repo (longer progress report)
Add at least one question and a very short progress report, relevant for others, in agenda
Update Project
Nominate for “Best PermaplanT Companion”-Awards KW15
Do at least 8 reviews of other PRs in this week (main repo and submissions)
Speak to your Buddy about glossary, what is missing, what could be extended?
Thesis: write Glossary&Goals (submission)
(Optional) Add review/correction/proof-read metadata for every paragraph in thesis, see unterlagen/paragraph_metadata.md
(Optional) Apply spelling.sed and checks to your thesis (see unterlagen)

Individual Tasks

To be done within next week KW14 (7.4.2023):

Yvonne: Logo, Drawings, Testing Seed entries, "Additional Name", Documentation of structs
Markus: Texts for landing page
Benjamin: plant search, creating a new layer, full text search
Gabriel: mdBook, testing strategy
Giancarlo: seed overview (edit, delete, ...)
Lukas: Frontend, Release Deployment, Import Seeds
Moritz: Finish Seed use case, create new layer, frontend tests
Nursultan: scraping, plant DB finalize, architecture, thesis correction
Paul: translation for frontend, Documentation Frontend, Seed fix
Ramzan: use cases, Database Guidelines, DB/ER Diagram, SQL code examples feasability, 1. QGis, 2. Projizieren, 3. Rastering
Samuel: landing page fixes, UI for plant use case (right toolbar), use cases
Thorben: use cases, DB/ER Diagram, Mockups, privacy, imprint, pricing, map

Agenda

09:00 welcome
- Best PermaplanT Companion KW15: Moritz
Stimmungsbarometer
Questions:
- buddy talk: glossary
Project: Planning for next iteration.
- please move tasks back if (significant) changes were requested
- please only keep "In Progress" if you really work on it that day
- please first request reviews from others before you request from me
target audience
- thesis: programmers
- PermaplanT: FLOSS contributors (could be biologists)
Frontend Meeting
- Implementation of Layers can be started!
- Landing page
- Layers/sidebar prototype
- Timeline
DB meeting
- Luciano helps with GIS
- coordinates
- Plant DB gets squashed to one migration
Preparation for In-Person Meeting
finish M1 this week
implement M2 this week

Meeting notes:

Glossary not complete, still some work to do
authentication setup tested with next cloud
openId connect plugin of Nextcloud did not work as expected and the limitations will stay
will host external identity provider
CORS: wasn't the problem -> actual routing problem fixed
decided to switch to async diesel in backend on all layers, no uses of web::block anymore
dark mode default, setting stored in local storage
FrontEnd docs, typedoc forked -> creating repo
db schema of hierarchies is not stable
invite at least one reviewer before markus takes a look (in case it is not urgent)
talk with Markus when adding synonyms in glossary
frontend meeting summary:
- changes in landing page
- decision of paul for localization
- current state of the toolbar
- went over moritz' mockup for timeline
- giancarlo finished the design for first layer
database meeting:
- Luciano - PostGIS expert
- squash all the migrations
translation in common instead of i18n
architecture decisions
- lazyloading of the map
- optimizations:
  - how and when does react rerender the components -> implement good data structure
  - how to represent 10 000 elements?
- offloading of the frontend state
- undo and redo
pull requests should not live longer than 2 weeks
1 scientifc name + 1 additional name (because there are plants with no scientific names yet)
live meeting in burgendland
- Unterfrauenhaid
- Feldgasse 19
- PLZ: 7321
- Train: Deutschkreutz
- Bus: Weppersdorf

Progress Reports

Please push progress reports in items below:

Benjamin: squash migrations, database schema
Nursultan:
- Scraping Permapeople #102. Should add enums, otherwise done.
- Scraping Reinsaat #123. There is an inconsistencies in the binomial names, currently pending. discussing with Yvonne. Otherwise done.
- Merging plant DB and Scrapers #217. Two tasks mentioned above should be separated from merging to avoid duplication of work. In progress.
- Architecture decisions #102. Small changes are still needed. In progress.
- Thesis. Done and waiting for feedback
Paul: added translation for seeds
Markus:
- Scientific name
- Datenschutz (privacy) page
- Cookie only after login
- use static map by default

Questions

Please push questions in items below:

Decisions

Please push Progress in decisions, or other important changes devs should know, in items below:

Outlook

To be done within next week KW15 (14.4.2023):

Test inserting seeds and report here
Finalize decisions #2
Write Forschungstagebuch in submissions repo (longer progress report)
Add at least one question and a very short progress report, relevant for others
Update Project
Nominate for “Best PermaplanT Companion”-Awards KW16
Do at least 8 reviews of other PRs in this week (main repo and submissions)
Thesis: write hypothesis, improve Glossary&Goals (submission)
Look at ways how to improve documentation (storybook or mdBook)
Speak to your Buddy: In-Person Meeting

Meeting 2023-04-18

Unfortunately no protocol was written

Attendees

Gabriel (Best PermaplanT Companion KW16)
Moritz (Best PermaplanT Companion KW15)
Samuel (Best PermaplanT Companion KW14)
Benjamin (Best PermaplanT Companion KW13)
Nursultan (Best PermaplanT Companion KW12)
Giancarlo (Best PermaplanT Companion KW11)
Paul
Ramzan
Markus
Yvonne

Unfortunately could not attend:

Thorben
Lukas

Buddies

Giancarlo & Moritz
Lukas & Gabriel
Samuel & Nursultan
Ramzan & Thorben
Benjamin & Paul

Tasks for Everyone

To be done before the meeting:

read the agenda, ask questions if anything is unclear

To be done within next week KW15 (14.4.2023):

Test inserting seeds locally (manual import from scraper still needed) and report here
Finalize decisions #2
Write Forschungstagebuch in submissions repo (longer progress report)
Push at least a very short progress report to the branch meeting_notes/18.04.2023
Update sprint plan
Nominate for “Best PermaplanT Companion”-Awards KW16
Do at least 8 reviews of other PRs in this week (main repo and submissions)
Thesis: write hypothesis, improve Glossary&Goals (submission)
Look at ways how to improve documentation (storybook or mdBook)
Speak to your Buddy: In-Person Meeting

Individual Tasks

To be done within next week KW15 (14.4.2023):

Moritz: create base layer, backend integration, finish frontend tests, timeline
Benjamin: creating a new layer, API description
Samuel: landing page finalize, UI for plant use case (right toolbar)
Gabriel: testing strategy, backend architecture,
Ramzan: endpoints map creation/deletion, DB/ER Diagram, SQL code examples feasability,
Paul: undo/redo, frontend testing
Giancarlo: drawing layer, seed overview (edit, delete, ...)
Lukas: frontend CI
Nursultan: scraping, plant DB finalize, architecture, thesis correction
Yvonne: Drawings, Documentation of structs
Markus: Texts for landing page
Thorben: TBD

Agenda

09:00 welcome
Gabriel (Best PermaplanT Companion KW16)
buddy talk: in-person meeting
sprint plan: Planning for next iteration.
PRs/Issues relevant for you:
finalize plant hierarchy
- added rank cultivar
- define unique name
- external_url, external_id
reviews:
- review fast, review others when reviewing buddy reviews
- use check list
- new item: check if i18n is done completely
- please say in the PR when you think work is blocked
- added please merge label
related work:
- should compare to your "approach"
- scientific, peer-reviewed citations
balance: properly test, document your work, no rush
Documentation&Tests
- Categories: mdBook, Storybook, rust code or API
- Put more links (within same category)
- in which category to put which documentation
- Frontend/Backend testing
M1 complete today ("Landing Page")
implement M2 this week

Progress Reports

Please push progress reports in items below:

Samuel:
- landing page: favicon, logo fix
- fixed existing linting errors
- auth decision
- todo & circle use cases
Benjamin:
- pagination: waiting for approvals
- map layers: reviewed PR from Giancarlo, seems easy to use
- plant search: did some investigation, implementation is blocked by pagination PR
Thorben:
- added more table descriptions to database schemata.
- map on landing page only load on manual click.
- added pricing and imprint page.
Lukas:
- Release Pipeline (#236) done
- Frontend Checks (#197) done

Questions

Please push questions in items below:

Samuel:
- Can we clean up PRs?
Benjamin:
- Can I clean up the backend structure? Some things seem messy.
  - Both entity and dto exists as file and directory in the model package. Shouldn't they both be a regular package of their own?
  - Both entity and dto split each struct and it's function implementations across two files. Wouldn't it make more sense to put struct and functions together into one file for each?
  - Why is dto part of the service layer? As this is the way we represent data in the api it fits better as subpackage of controller.
  - Intersection of layers. The service layer should be the one acting between controllers and database. Why do controllers get the database connection pool as argument when this would better fit the service layer? Why does the database layer handle mapping from entity to dto when this should belong in the service layer?

Decisions

Please push progress in decisions, or other important changes devs should know, in items below:

add here

Outlook

create issues

To be done within next week 21.4.2023 (KW16):

Speak to your buddy
Create issue(s) and implement your use case(s) as assigned
Write Forschungstagebuch
Push at least a very short progress report to the branch meeting_notes/25.04.2023
Update sprint plan (see queries above)
Nominate for “Best PermaplanT Companion”-Awards KW17
Do at least 8 reviews of other PRs in this week in main repo and submissions (see about reviews above)
Thesis: add related work (5 citations)
Create a PR to improve documentation: API, storybook or mdBook

Meeting 2023-04-25

Protocolled by: Thorben

Attendees

Gabriel (Best PermaplanT Companion KW16)
Moritz (Best PermaplanT Companion KW15)
Samuel (Best PermaplanT Companion KW14)
Giancarlo (Best PermaplanT Companion KW11)
Paul
Thorben
Markus
Yvonne (Birthday)

Cannot come:

Lukas
Ramzan (Best PermaplanT Companion KW17)

Farewell:

Nursultan (Finished, Best PermaplanT Companion KW12)
Benjamin (Aborted, Best PermaplanT Companion KW13)

Buddies

Giancarlo & Moritz
Lukas & Gabriel
Ramzan & Thorben
Samuel & Paul

Tasks for Everyone

To be done until 21.4.2023 (KW16):

Cleanup your old issues you can find with the links provided last time:
Create issues as needed for the current sprint, in particular for your assigned use case and individual tasks
Speak to your buddy about related work
Implement your use case(s) as assigned in /doc/usecases.
Write Forschungstagebuch
Push at least a very short progress report to the branch meeting_notes/25.04.2023
Update sprint plan (see queries above)
Nominate for “Best PermaplanT Companion”-Awards KW17
Do at least 8 reviews of other PRs in this week in main repo and submissions (see about reviews above)
Thesis: add related work (5 citations)
Thesis: check citations of others (if you find better/more recent/peer-reviewed citations)
Create at least one PR to improve documentation: API, storybook or mdBook

Individual Tasks

To be done until 21.4.2023 (KW16):

Gabriel: auth, testing strategy, backend architecture,
Thorben: map creation/deletion full stack (UI, end point, database)
Benjamin: polyculture -> Moritz/Paul; search -> Gabriel
Moritz: create base layer
Samuel: UI for plant use case (left toolbar), Lib suchen, frontend auth
Paul: undo/redo, timeline
Ramzan: Map Versioning (SQL+end points for loading/saving versions of maps), DB/ER Diagram, SQL code examples feasability
Giancarlo: copy&paste, drawing layer, seed overview (edit, delete, ...)
Yvonne: Drawings, Documentation of structs
Markus: Dokumentation

Agenda

09:00 welcome
protocol
special honors and celebrations:
- Ramzan (Best PermaplanT Companion KW17)
- Yvonne (Birthday)
- new buddies: Samuel & Paul
individual tasks (which of are you proud of)
sprint plan: Planning for next iteration.
show nursultan's thesis, 70/20/10
contributions of your work:
- what you implemented/reviewed/...
- new scientific results
- new methodology
- reproduction
procrastination
- cannot directly switching off thoughts, instead movement, nature, meditation
- buddies etc. (healthy social system)
- "wöchentliche schaffbare Happen"
backlog:
- importance of progress reports/questions/decisions
- documentation for yourself
M1 celebration "landing page"
- media coverage: https://linuxnews.de/interview-markus-raab-von-elektra/
finish M2
time to say goodbye:
- Nursultan (Finished, Best PermaplanT Companion KW12)
- Benjamin (Aborted, Best PermaplanT Companion KW13)

Meeting Notes

Icebreaker Game
What progress are we proud of this week?
- Testing strategy for backend finished
- Seed edit & delete complete
- Base layer editor made good progress
- DB scraper finished and works
- Map undo/redo nearly finished
- Improvements on the website
Sprint Progress
- Done:
  - Published first release
  - Frontend bugfixes
  - Third scraper finished
- In Progress:
  - map creation/deletion
  - authentication
  - editor toolbar
- To be done:
  - Full-text search
A look at Nursultans Thesis (good job! 👍)
Alternatives to procrastination:
- Meditation
- Taking a walk in nature
- Talk to Markus/your Buddy
Reduce polyculture tasks to data import due to Benjamin having to leave the team

Progress Reports

Moritz
- Submitted PR for frontend testing setup.
- Started work on base layer.
- Submitted related work / citations for thesis.
Paul
- Implemented most of undo-redo use case.
Samuel
- Integrated right toolbar for map editor
- landing page improvements for release (texts, pictures)
Lukas
- Release Pipeline
- Infrastructure
Gabriel
- Testing Strategy: Decision
- Testing Strategy: Test cleanup (Reviewing)
- Backend architecture (WIP)

Questions

Please push questions in items below:

open issues/problems
- Gabriel: weekend work
- Giancarlo: copy&paste
- Moritz: find time
- Nursultan: scraper double insert
- Paul: undo/redo
- Samuel: new task
- Thorben: backend

Changelog

Please push progress important changes devs should know, e.g. decisions, in items below:

Plant Search Decision: https://github.com/ElektraInitiative/PermaplanT/pull/309

Outlook

To be done until 28.4.2023 (KW16):

Speak to your buddy about contributions
Finish/integrate your implementation of use case(s) as assigned in /doc/usecases.
Write Forschungstagebuch
Push at least a very short changelog to the branch meeting_notes/25.04.2023
Update sprint plan (see queries above)
Nominate for “Best PermaplanT Companion”-Awards KW18 (without Nursultan and Benjamin)
Do at least 8 reviews of other PRs in this week in main repo and submissions (see about reviews above)
Thesis: add contributions
Create issues of favorite things you would like to do
Create at least one PR to improve documentation: API, storybook or mdBook

Individual Tasks

To be done until 28.4.2023 (KW16):

Gabriel: auth, testing strategy, backend architecture,
Thorben: map creation/deletion full stack (UI, end point, database)
Benjamin: polyculture -> Moritz/Paul; search -> Gabriel
Moritz: create base layer
Samuel: UI for plant use case (left toolbar), Lib suchen, frontend auth
Paul: undo/redo, timeline
Ramzan: Map Versioning (SQL+end points for loading/saving versions of maps), DB/ER Diagram, SQL code examples feasability
Giancarlo: copy&paste, drawing layer, seed overview (edit, delete, ...)
Yvonne: Drawings, Documentation of structs
Markus: Documentation

Meeting 2023-04-27 DB

Protocolled by: Gabriel

Attendees

Luciano
Markus
Yvonne
(everyone on the mailing list is welcomed)

Could not come on short notice:

Moritz
Thorben
Ramzan

Preparations

add yourself in https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/16
add previous outcomes
add questions for Luciano

Previous outcomes

We use KonvaJS as Canvas
Alterantives would be:
- kepler.gl can use lang/lat coordinate systems
- LeafletJS
Canvas has cartesian coordinate system
We use 3D geometry, z-value is 0 if no height given
The user draws a polygon to define the size of the map
coordinates in the database
can use different coordinate systems. but costly
PostGIS can store raster information in the database
- user can brush to draw raster areas

Please add relevant outcomes (what we already know)

Questions

Which coordinate system do we use?
- real-world longitude and latitude?
- what if user does not want to give longitude and latitude?
- how to performantly transform to cartesian coordinate system?
How to store coordinates in the database?
- allow different coordinate systems? -> no, we use WGS84
- migration of data, trivial with (startpoint, endpoint)
- store both real-world and cartesian for performance? -> no, it is efficient enough
5D mapping? How to efficiently select for time+alternatives?
geo referencing with ST_SetGeoReference? -> polygon for rastering maybe, it is only for rastering inside the database
Rastering for rain, sun, etc? -> we won't do, use polygons instead
Does the size of the map need to be static? -> expanding should be okay, warning for plants that are outside

Please add further questions to Luciano

Example query:

CREATE TABLE geometries (name varchar, geom geometry);

INSERT INTO geometries VALUES ('Point', 'POINT(0 0)'),
('Linestring', 'LINESTRING(0 0, 1 1, 2 1, 2 2)'),
('Polygon', 'POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'),
('PolygonWithHole', 'POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 1 2, 2 2, 2 1, 1 1))'),
('Collection', 'GEOMETRYCOLLECTION(POINT(2 0),POLYGON((0 0, 1 0, 1 1, 0 1, 0 0)))');

SELECT name, ST_AsText(geom) FROM geometries;

Agenda

13:00 start
protocol
welcome ☺️
maybe Moritz shows current status?
DB Design
answer/discuss questions
who wants to work on which task?

Tasks

Luciano: real-world example for (inserting) DB (for people that don't have/want to use real location), including transformation to cartesian coordinate system, boundary polygon (ST_SetGeoReference?), relationship of elements to boundary, PostGIS computation/algorithms for the use cases, smoothing of polygons

Notes

Currently we use cartesian coordinates with pixels representing x,y coordinates. Switch? Use lat,long. If users have privacy concerns (don't want to give their coords use 0,0 for lower left).

Coord Sys: WGS84 code: EPSG 4326

How to store coords in database? store real coords in database translate to the ones used by the frontend when querying? see tasks

Asking users for coords: Allow for inprecise input? How to change coords

Don't allow different coordinate systems

5D mapping: Luciano looks into it, prob just timestamp

Rastering requires some thinking

Meeting 2023-05-02

Protocolled by: Samuel

Attendees

Ramzan (Best PermaplanT Companion KW17)
Gabriel (Best PermaplanT Companion KW16)
Moritz (Best PermaplanT Companion KW15)
Samuel (Best PermaplanT Companion KW14)
Thorben
Lukas
Markus
Yvonne

Unfortunately cannot attend:

Paul
Giancarlo (Best PermaplanT Companion KW11)

Buddies

Giancarlo & Moritz
Lukas & Gabriel
Ramzan & Thorben
Samuel & Paul

Tasks for Everyone

To be done until 28.4.2023 (KW17):

Speak to your buddy about contributions
Finish/integrate your implementation of use case(s) as assigned in /doc/usecases.
Write Forschungstagebuch
Push at least a very short Changelog and Progress Report to the branch meeting_notes/02.05.2023
Update sprint plan
Do at least 8 reviews of other PRs in this week in main repo and submissions
Thesis: add (potential) contributions
Create issues of favorite things you would like to do

Individual Tasks

To be done until 28.4.2023 (KW17):

Paul: frontend architecture, timeline
Giancarlo: copy&paste, plants layer drag&drop
Ramzan: Post GIS
Samuel: UI for plant use case (toolbar), frontend auth, layer enable
Gabriel: auth, testing strategy, new unit tests
Thorben: map creation with versions full stack (UI, end point, database)
Moritz: base layer, DB review
Yvonne: Drawings, https://tablericons.com
Markus: PRs mergen

Agenda

09:00 welcome
protocol: Samuel
switch to German spoken
game: true/false question
which task do you postpone most?
- cron deletion
- writing on the thesis
- search feature
GIS outcome
- fixed coordinate system: WGS84
- we are expecting postGIS examples (usecases implemented in SQL)
Review Process
- create issues shortly explaining what you want to do (before Friday!)
- create PR, assign two persons for review
- incorporate feedback and assign @markus2330 for review (before Friday!)
- if there are at least two "approved" and no "requested changes", everyone except the PR author can merge
- in case of doubt, let @markus2330 merge
server:
- local checkout of Nextcloud
- keycloak shared or for testing? -> mutliple realms managed, in .env URL+realm
fixed hours of work
brainstorming about end-user documentation (https://github.com/ElektraInitiative/PermaplanT/issues/328)
- gamification
- hover tooltip/title (makes most sense)
- chatGPT/GPT4 in combination with a vector DB -> generate answers for questions
- tourguide/tutorial
- faq/handbook (probably a lot of effort)
- notes/hints during loading times
- videos
sprint plan: Planning for next iteration. done: - unit tests (backend and frontend) - entity documentation
backlog:
- importance of progress reports/questions/decisions
- documentation for yourself
finish second milestone: 5.5.2023

Changelogs

Please push progress important changes devs should know, e.g. decisions, in items below:

Questions

Please push questions in items below:

Progress Reports

Please push a short progress report in items below:

Samuel: improved toolbar (left bar, introduced dependency react-draggable, placeholder content for left bar, pass content as props), research on oidc client lib
Gabriel: backend architecture documentation (Review), graceful shutdown (Review), OAuth2 backend (WIP)
Lukas: Scraper Data in CI
Thorben: Map overview page and map creation prototype

Outlook

To be done until 5.5.2023 (KW18):

Merge all PRs for plants use case: integrated UI
Speak to your buddy about fixed hours
update your README in submissions: fixed hours, contact data etc.
Write Forschungstagebuch
Push at least a very short Changelog and Progress Report to the branch meeting_notes/9.5.2023
Update sprint plan
Do at least 8 reviews of other PRs in this week in main repo and submissions
Thesis: write any page you feel like, Free Writing
Nominate for “Best PermaplanT Companion”-Awards KW19 (now without Nursultan and Benjamin, we will miss them!)

Meeting 2023-05-09

Protocolled by: Moritz

Attendees

Gabriel
Moritz
Samuel
Giancarlo
Thorben
Lukas
Paul
Markus
Yvonne

Fehlt:

Ramzan

Buddies

Giancarlo & Moritz
Lukas & Gabriel
Ramzan & Thorben
Samuel & Paul

Tasks for Everyone

To be done until 5.5.2023 (KW18):

Get all PRs for plants use case merged, so that we have a integrated UI with all parts
Speak to your buddy about fixed hours
update your README in submissions: fixed hours, contact data etc.
Write Forschungstagebuch
Push at least a very short Changelog and Progress Report to the branch meeting_notes/9.5.2023
Update sprint plan
Do at least 8 reviews of other PRs in this week in main repo and submissions
Thesis: write any page you feel like, Free Writing
Nominate for “Best PermaplanT Companion”-Awards KW19 (now without Nursultan and Benjamin, we will miss them!)

Individual Tasks

To be done until 5.5.2023 (KW18):

Ramzan: Post GIS
Paul: frontend architecture, timeline
Giancarlo: copy&paste (nach redo), plants layer drag&drop (offen), seeds edit&delete (nur CI fixen)
Samuel: state refactoring, frontend auth
Gabriel: auth, testing strategy, new unit tests
Thorben: map creation with versions full stack (UI, end point, database)
Moritz: base layer (SimpleForm offen), DB review
Lukas: keycloak
Yvonne: Drawings, https://tablericons.com
Markus: PRs mergen

Individual Tasks

To be done until 12.5.2023 (KW19):

Paul: frontend architecture, timeline
Giancarlo: copy&paste (nach redo), seeds edit&delete (nur CI fixen), plants layer drag&drop (offen)
Samuel: state refactoring, frontend auth, components documentation
Gabriel: auth, testing strategy, new integration tests, plant search
Moritz: base layer (SimpleForm offen), DB review, base layer specific for maps+polygons, integration for plants layer
Thorben: map creation+alte PRs me, DB, Versioning, save&load, map properties
Lukas: keycloak, left-over issues
Yvonne: Pavlo, https://tablericons.com
Markus: PRs mergen

Agenda

09:00 welcome
protocol
game: true/false question
team, team, team
- for benchmarks?
- for user study? (Thorben/Giancarlo)
- https://chrome.google.com/webstore/detail/lighthouse/blipmdconlkpinefehnmjammfjpmpbjk?hl=en
English&Thesis
- mood changer
- line breaks in text
- avoid modal verbs
- methods: only what is actually used
large scale programming
- write more assertions
- end-to-end tests summary
sprint plan
milestone M2 finished

Changelogs

Please push progress important changes devs should know, e.g. decisions, in items below:

OAuth2
decision: 5 sec timeout
decision: keybindings in JSON files
companions table

Questions

Please push questions in items below:

Progress Reports

Please push a short progress report in items below:

Gabriel: documentation of backend architecture (merged), OAuth2 in backend (review)
Samuel: finished toolbar (#315, #189), toolbar integration ready for review after #244 and #306 are merged, WIP: frontend auth
Moritz: finish base layer PR (update from review needed)

Outlook

finish M2: plant UI, auth, maps DB, user-specific seeds
talk to (non-)buddies: collaboration for benchmark/user study
Push at least a very short Changelog and Progress Report to the branch meeting_notes/16.5.2023
Update sprint plan
Do at least 8 reviews of other PRs in this week in main repo and submissions
Thesis: Write Refinement of Methods (Reviews Next week)
Update doc/authors.md (May)
Create PR improving design by contract/assertions

Meeting Notes

Small warm up game.
Teams for evaluation
- BSc. students performing a user study or a benchmark should get toghether and unify their processes.
- This might reduce the time to perform benchmarks for multiple componenets.
- Gabriel: consider using Lighthouse for frontend evaluation
English in context of BSc. thesis. and reviews.
- mood changers (but, however, ...):
- Can be left out entirely and replaced by paragraphs
- However is a bit complicated to use. E.g. don't use at the end of a sentence.
- Phrases should not be changed.
- Line break after each sentence
- Modal verbs (can, might, may, ...). Should be used to communicate probailities in technical contexts. Its best to avoid them throughout the thesis.
Methodology section
- Should only contain methodologies that are actually used.
Progress reports
- Communicate changes of scope early (e.g. something can not be done within a week).
- More feedback (especially until friday).
- Be open about mistakes.
- Put weekly changes into progress report so that other team members get an overview of what changed.
Pablo sent a comprehensive companion list
Update/Cleanup of issue board
- We need to make sure that debugging does not become to cumbersome.
- Design by contract should be used internally to avoid mistakes.
- Should be enforced using assertions.
- How and where this will be used still needs to be figured out.

Meeting 2023-05-16

Protocolled by: Felix

Attendees

Gabriel (Protocol)
Moritz (Protocol)
Lukas (Protocol)
Samuel (Protocol)
Paul (Protocol)
Felix
Markus
Yvonne

Cannot attend:

Thorben (Protocol)
Giancarlo
Ramzan

Buddies

Giancarlo & Moritz
Lukas & Gabriel & Felix
Ramzan & Thorben
Samuel & Paul

Tasks for Everyone

To be done until 12.5.2023 (KW19):

https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/17
talk to (non-)buddies: collaboration for benchmark/user study
Push at least a very short Changelog and Progress Report to the branch meeting_notes/16.5.2023
Update sprint plan
Do at least 8 reviews of other PRs in this week in main repo and submissions
Thesis: Write Refinement of Methods (Reviews Next week)
Update doc/authors.md (May)
Create PR improving design by contract/assertions
finish or report all tasks related to M2: plant UI, auth, maps DB, user-specific seeds

Individual Tasks

To be done until 12.5.2023 (KW19):

Paul: UC timeline
Gabriel: UC plant search, (log)
Samuel: frontend auth, state refactoring, (components documentation), UC auth
Moritz: base layer UC with fixed scale, DB review, (postgis?)
Giancarlo: copy&paste (nach redo), drawing layer integrate, seeds edit&delete (nur CI fixen), plants layer drag&drop (offen)
Thorben: map creation+alte PRs me, DB, Versioning, save&load, map properties
Ramzan: PostGIS
Lukas: PR permaplant, auth docu, (cargo)
Felix: pre-commit, (priority, emails)
Yvonne: Pavlo, https://tablericons.com
Markus: use cases restructure

Agenda

09:00 welcome
protocol
Welcome Felix (help with CI)
Introduction game
progress: - strict deadline for small tasks (e.g. voting) - best-effort for larger tasks (e.g. implementing features): immediate states before review is possible etc. ok
Definition of Done (of a use case) - documentation: clear for others how changes/extensions should be done - integration tests: demonstrate what works - issues closed: moved to Done in https://github.com/orgs/ElektraInitiative/projects/4/views/1 - mark as "Done" in use case + changed if necessary - write Changelog for meeting
sprint plan
Retrospective first Half
progress M2: - layers/base_layer.md - polygon of border - layers/plants_layer.md - plant plants
Tools - https://unlighthouse.dev/ - https://github.com/flamegraph-rs/flamegraph - valgrind
conclusion: faults of the month

Changelogs

Please push progress important changes devs should know, e.g. decisions, in items below:

auth
frontend integration
architecture: https://github.com/ElektraInitiative/PermaplanT/pull/352

Progress Reports

Please push a short progress report in items below:

Giancarlo
- Adding plant from toolbar
- And Copy & Paste of shapes

Outlook

To be done until 19.5.2023:

talk to (non-)buddies: tooling for benchmarks etc.
Push at least a very short Changelog to the branch meeting_notes/23.5.2023
Update sprint plan
Do at least 8 reviews of other PRs in this week in main repo and submissions
Thesis: create PR with one two sentences till tomorrow, review

Meeting Notes

Allgemein

Deadlines bis Freitag (kleine Tasks)
Dokumentation/Reviews wichtig
Test
Issues schließen
usecases auch updaten
Changelog nicht unbedingt, sondern in Meeting-Notes

Sprint

nc integration noch offen (Lukas)
frontend arch. Issue kleine Problem (Paul)
Base Layer (unused import) (Moritz)
frontend arch. alle anschauen
Dokumentation hinzufügen (Samuel)
Merge bald wie möglich
PostGIS-Diesel-PlugIn problem; manuell lösbar (Moritz)

Meeting 2023-05-23

Protocolled by: Moritz

Attendees

Moritz (Protokoll)
Gabriel
Samuel
Paul
Lukas
Felix
Thorben
Markus
Yvonne

Nicht da:

Giancarlo
Ramzan

Buddies

Giancarlo & Moritz
Lukas & Felix
Gabriel & Thorben
Samuel & Paul

Tasks for Everyone

To be done until 26.5.2023 (except of text):

Talk to buddies: tooling for benchmarks etc.
Push at least a very short Changelog to the branch meeting_notes/23.05.2023
Update sprint plan
Do at least 8 reviews of other PRs in this week in main repo and submissions
create PR in submissions with one two sentences of any text until 17.05.2023
review 2 other thesis by writing at least following 3 points:
1. shortly say what you think that the author wanted to say
2. which sentence was the most difficult one to read
3. which are the (main) terms and are they used consistently

Individual Tasks

To be done until 26.5.2023:

Paul: UC timeline
Gabriel: UC plant search, (log)
Samuel: UC auth, frontend auth, state refactoring, (components documentation)
Moritz: UC base layer with fixed scale, DB review, (postgis?)
Giancarlo: UC plants, copy&paste (nach redo), drawing layer integrate, seeds edit&delete (nur CI fixen), plants layer drag&drop (offen)
Thorben: UC map creation, map properties
Ramzan: PostGIS
Lukas: PR permaplant, auth docu, (cargo)
Felix: pre-commit, (priority, emails)
Yvonne: Pavlo, https://tablericons.com
Markus: use cases restructure

UC refers to a use case should be ddone within this sprint.

Agenda

09:00 welcome
permaculture principles
protocol: Moritz
buddy talk: toolings
Changelogs
sprint plan
reporting CI issues:
- retrigger, see doc/ci.md
- create issue with error message
- on urgent cases contact Lukas or Felix
last decisions https://github.com/ElektraInitiative/PermaplanT/issues/2
improve use cases https://github.com/ElektraInitiative/PermaplanT/pull/366
immediately fix CI problems/reviews in your PRs (as you want fast CI times/reviews)
how to review

Changelogs

Please push progress important changes devs should know, e.g. decisions, in items below:

Markus:
- improve use cases: https://github.com/ElektraInitiative/PermaplanT/pull/366
Paul:
- architecture: https://github.com/ElektraInitiative/PermaplanT/pull/352
Gabriel:
- backend auth: https://github.com/ElektraInitiative/PermaplanT/pull/330 (merged into frontend auth, see Samuel's comment below)
- plants full-text search: https://github.com/ElektraInitiative/PermaplanT/pull/367
- more integration tests: https://github.com/ElektraInitiative/PermaplanT/pull/354
Samuel:
- frontend auth: https://github.com/ElektraInitiative/PermaplanT/pull/351
  - axios configuration wrapper in 'frontend/src/axios' import and call createAPI() for requests to the backend and createNextcloudAPI() for requests to Nextcloud example:
```
import { createAPI } from "@/config/axios";
const http = createAPI();
try {
  await http.post<SeedDto>("/api/seeds", seed);
} catch (error) {
  throw error as Error;
}
```
Moritz:
base layer:
Implement feedback on base layer PR
Get PostGIS to work (somewhat)
Discuss goals for this feature

Outlook

Talk to buddies: tooling for benchmarks etc.
Push at least a very short Changelog to the branch meeting_notes/30.05.2023
Update sprint plan
Do at least 8 reviews of other PRs in this week in main repo and submissions
create PR in submissions with one two sentences of any text until 17.05.2023
review 2 other thesis by writing at least following 3 points:
1. shortly say what you think that the author wanted to say
2. which sentence was the most difficult one to read
3. which are the (main) terms and are they used consistently
Outlook Tasks
Moritz: UC base layer with fixed scale, DB review https://github.com/ElektraInitiative/PermaplanT/pull/287, (postgis?)
Paul: UC timeline, offline
Gabriel: UC plant search, decision, (log)
Samuel: UC auth, frontend auth, state refactoring, (components documentation)
Thorben: UC map creation, map properties, membership application
Giancarlo: UC plants, copy&paste (nach redo), drawing layer integrate, seeds edit&delete (nur CI fixen), plants layer drag&drop (offen)
Ramzan: PostGIS
Lukas: auth ansible, (cargo)
Felix: pre-commit, priority, (emails)
Yvonne: Plant Relations
Markus: use cases mergen, nextcloud migration

UC refers to a use case should be done within this sprint.

Meeting Notes

Warmup Game: Permaculture principles
Buddies
Some restructuring
Ramzan is no longer part of PermaplanT
Gabriel and Thorben are in a group
Lukas and Felix are in a group
Tooling:
Paul and Samuel:
React Dev Tools and Chromium Lighthouse seem to be handy for evaluating frontend performance
Change log:
Should also contain changes that are not reflected in GitHub PRs (e.g. changes to Dockerfiles)
Toolbar integration:
There are two slots per component in BaseStage where configurations can be added.
In the left toolbar: just hook into the button events
Details will be added Samuel
Error messages:
Make it hard to do things wrong and if thats not possible provide descriptive error messages
Progress reports:
Client Authentication: If the backend is not reachable, the website should still function.
Base Layer: goes back to in Progress to integrate with new layers toolbars
DB Schema: more reviews required
Testing strategy: merge auth change before this PR
Use cases have been restructured:
Organized into folders akin to our Kanban board
Usecases should be moved as required
Status in Summary has been removed
If build fails:
Retrigger build according to documentation
If that fails, open an isse
Lukas/Felix will be responsible to fix said issue
Decisions:
News: research how to implement RSS feed
Paul shold research offline vs collaborative undo/redo
Membership onboarding should be done via keycloak
Thorben volunteered to look at onboarding in keycloak
Gabriel was assigned to look at SMTP integration
Thesis Reviews
More reviews wuld be great

Meeting 2023-05-26 Architecture

Participants

Paul
Thorben
Moritz
Samuel
Lukas (Zuhörer)

Questions

The main architectural questions are:

current state? (layers state+backend)
- array, actions
lock
When to submit data to the backend?
multi-player?
SSE
How to send data to the backend?
- array von actions
How to get updates from the changes of other users?
Scope of versions, undo/redo
- tracked/untracked history
how separated are layers
Collaborative vs. Offline
Locking of layers
undo/redo
removing versions?
timeline (createdAt, deletedAt) -> many year span not considered yet
actions associated with layer
map owner can remove locks
without lock offline: read-only state
lösung:
- backend always up-to-date
- collaborativ: see what others are doing
- only conflicts in most recent actions
- undo/redo history gets purged on movement
- lazy loading of layers (not years)
- we need reverse actions
- separated from it then IS-state (not initial)
- begin, end date different to delete!
- coordinates: konva coordinate CSS pixel = 1cm
- objects: x,y,scale,color, shape, ID, rotation
- per layer API calls
- plant API calls:
  1. search (text) -> list of plants
  2. plant_info () -> info, list plant_ID of relations, array of 1m raster, maybe picture/heat map
  3. place_plant (plant_ID, pos, date)
- map versions löschen
- remember which objects are loaded?
- elemente in DB store

outcome:

moritz: auth, image, pixels docu
paul: lazy loading, state management
samuel: NC, state
Thorben: remove versioning, map duplication

We would then have to keep track of the undo/redo history for each user on the backend as well. -> we don't do The read-only users should only have the latest version of the data + their local changes in the history. Without keeping track of the undo/redo history on the backend, sending a new version to the backend at a fast pace would clutter it.

Please also read (with my comments): https://github.com/ElektraInitiative/PermaplanT/pull/382/files

Meeting Notes

Undo/Redo
Current plan:
- base state + actions taken until now
- synchronize with backend via version creation, backend takes actions and builds new base state
- proposition: save actions in backend to restore lost sessions
- could cause synchronization problems with offline functionality
- implement locks on layers to reduce synchronization conflicts
- problem: what happens if user loses lock while offline and then comes online again
- "multiplayer" szenario: every user tracks only their own history
- how does undo/redo interact with very old changes (e.g. 10 years ago)
- do not load every data, only when needed (lazy loading)
- remove local history of one layer if another user made changes on it
new plan:
- directly push changes to backend
- every layer has its own endpoints
- history holds undo actions
Frontend map store
- tracked and untracked states
- tracked: affected by undo/redo
- untracked: configurations (e.g. layer opacity)
- layer independent store => to be used by all layers
Backend interaction with offline use case
- lock backend writes on map when going offline
- offline capability as a grantable permission for collaboration
- map owner should be able to revoke write lock in case of an abuse of offline mode
- as a first step no write lock, instead read only when offline
Save creation and disable dates for every element, "deleting" a plant sets it disabled to still be able to view it in the timeline
Position of elements will not be saved for the timeline and instead gets overwritten with every coordinate change

Meeting 2023-05-30

Protocolled by: Gabriel

Attendees

Gabriel (Protokoll)
Moritz (Protokoll done)
Paul
Felix
Thorben
Markus
Yvonne
Samuel (later)

Not here:

Giancarlo

Cannot attend:

Lukas

Buddies

Giancarlo & Moritz
Lukas & Felix
Gabriel & Thorben
Samuel & Paul

Tasks for Everyone

To be done until 26.5.2023 (except of reviews):

Get your use case (UC) done
Self-register in keycloak (https://auth.permaplant.net)
Talk to buddies: Talk about what you would like to read in Changelogs
Push at least a very short Changelog to the branch meeting_notes/30.05.2023
Update sprint plan
Create PR in submissions with the introduction of your thesis
Do at least 8 reviews of other PRs
Review 2 other thesis (in submission) by writing at least following 3 points:
1. shortly say what you think that the author wanted to say
2. which sentence was the most difficult one to read
3. which are the (main) terms and are they used consistently

Individual Tasks

To be done until 26.5.2023:

Samuel: UC auth, state refactoring, NC photos, components documentation
Paul: UC timeline, offline architecture/decisions
Thorben: UC map creation, map properties, membership application
Moritz: UC base layer with fixed scale
Gabriel: UC map search, API for plants, decision, (log)
Felix: pre-commit, priority, (emails)
Giancarlo: UC plants, copy&paste, drawing layer integrate, seeds edit&delete (nur CI fixen), plants layer drag&drop (offen)
Lukas: auth ansible, (cargo)
Yvonne: Plant Relations
Markus: Nextcloud migration

Agenda

09:00 welcome
protocol: Gabriel
permaculture principles part II
Changelogs
sprint plan
finalize architecture https://github.com/ElektraInitiative/PermaplanT/pull/385
- please read
- strategy: database and state always contains the latest data (server-sent events)
- observer pattern in backend?
- calculations done in backend
- layer implementations separated but with shared implementation
- low memory consumption: lazy-loading and offloading (only keep used layers in memory)
development:
- please make sure that documentation gets improved in every PR
- PRs are often a very inefficient way to clarify objectives
- follow-up issues
- guidelines
- If not yet part of master, Changelogs should contain refs to issues, PRs
- pump npm version (current: v19.4.0 the default npm version is v9.2.0)
- UI guidelines
outlook

Changelogs

Please push progress important changes devs should know, e.g. decisions, in items with syntax - change _(Your Name)_ below:

Auth:

now active, requires either a user on https://auth.permaplant.net/ (can be aquired by visiting https://pr.permaplant.net/, clicking login and register) or a local setup of Keycloak (see readme in backend)
doc on how to obtain tokens for local development is still missing (e.g. OAuth2 via Postman or curl) #392
local swagger doc broken (tracked by #383)

Nextcloud:

introduced webdav library
introduced utility functions for fetching and uploading images to Nextcloud as well as a webdav test component (webdav-test.tsx) for testing this functionality. It is currently available at /webdav
disable CORS in your browser for Nextcloud feature development: e.g. google-chrome --disable-web-security or chromium --disable-web-security This is needed to allow requests which are not under the some origin. More info about Nextcloud setup in /doc/setups/nextcloud/README.md

map state management:

The state is now split in two parts namely tracked and untracked map store. More info about the state management of layers in the map editor is available in /doc/architecture/frontend.md

general:

finish last decisions https://github.com/ElektraInitiative/PermaplanT/issues/2
- RSS and email libs found
use cases improved https://github.com/ElektraInitiative/PermaplanT/pull/366

Outlook

To be done until 2.6.2023:

Vote for date https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/18
Get your use case (UC) done
Talk to buddy: permaculture principles
update authors.md for last month
add related work/introduction for your thesis in submissions
Push at least a very short Changelog to the branch meeting_notes/7.6.2023
Update sprint plan
Do at least 8 reviews of other PRs

Individual Tasks

To be done until 2.6.2023:

Moritz: UC base layer with fixed scale in frontend, with NC images, plant/seed/(map) search, UC plant search
Samuel: NC photos: for maps+base layer, components documentation, NC strukturen (circles, gruppen), landing page: (1) 2x chat msg, (2) chat window (3) gallery
Paul: tracer bullet architektur, offline architecture/decisions, SSE offline?
Thorben: UC map creation, maps+layer API, membership application: user in our DB
Gabriel: API for plants, UC auth, (UC map search, decision, log), API plant/base layer
Felix: pre-commit, priority, emails
Giancarlo: UC plants, copy&paste, drawing layer integrate, seeds edit&delete (nur CI fixen), plants layer drag&drop (offen)
Lukas: auth ansible, (cargo)
Yvonne: Plant Relations
Markus: API

Meeting Notes

Allgemein:

Talk with buddy about how to integrate 'Observe and interact' and 'Apply self-regulation and acept feedback' in thesis
more documentation, write where problems are (Are they in implementation, decision or use-case?)

Sprint:

fetch images from Nextcloud with Webdav (Samuel)
undo/redo via SSE (Paul)
unique constraint af map name (Thorben)
layer impl in frontend (Moritz)
auth (Samuel, Gabriel)
more integration tests (Gabriel)
mail client/rss generator decision (Gabriel)
plants full-text search (WIP; Gabriel)
architecture doc (WIP; Markus)

Meeting 2023-06-06

Protocolled by: Samuel

Attendees

Christoph
Samuel (Protokoll)
Gabriel (Protokoll done)
Moritz (Protokoll done)
Paul
Felix
Thorben
Lukas
Markus
Yvonne

Nicht da:

Giancarlo

Buddies

Lukas & Felix & Christoph
Giancarlo & Moritz
Gabriel & Thorben
Samuel & Paul

Tasks for Everyone

To be done until 2.6.2023:

Vote for date https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/18
Get at least one use case (UC) done
Talk to buddy: permaculture principles
update authors.md for last month (June)
add related work/introduction for your thesis in submissions
Push at least a short Changelog to the branch meeting_notes/06.06.2023 (new syntax, see below)
Update sprint plan
Do at least 8 reviews of other PRs in main repo or submissions
Read architecture (already merged) available as mdbook, see main README.md Part I

Individual Tasks

To be done until 2.6.2023, ordered by priority:

Moritz: finish UC plant search, UC base layer with fixed scale in frontend with NC images, seed/(map) search in frontend
Samuel: NC photos: for maps+base layer, components documentation, NC strukturen (circles, gruppen), landing page: (1) 2x chat msg, (2) chat window (3) gallery
Paul: tracer bullet architektur, offline architecture/decisions, SEE offline? etc.
Thorben: UC map creation, maps+layer API, membership application: user in our DB
Gabriel: API for plants, UC auth, (UC map search, decision, log), API plant/base layer
Felix: pre-commit, priority, emails
Giancarlo: UC plants, copy&paste, drawing layer integrate, seeds edit&delete (nur CI fixen), plants layer drag&drop (offen)
Lukas: Nextcloud, auth ansible, (cargo

Agenda

09:00 welcome
welcome Christoph (DB, Nextcloud, Security)
permaculture principles part III
protocol: Samuel
FLOSS
- tutor
- issues
issues which are handled by students in the next semester (should be simple and concise)
excellent specification is valued as almost done
good first issue label (will be renamed to FLOSS)
break
coordination
- responsibility to implement use cases fully (or ask if you think implementation needs intermediate steps)
- pulling in of libs (zod): write about it in decisions or in solution
problems with typeshare: no validation -> zod as validation library to solve this
no error when types are mismatching
write a few sentences in solutions for the use cases of zod
grading:
- 10, 20, 70
- 10: thesis is smallest task but has to be done
- 20: review and help the team
- 70: implementation / individual work for the project
- quality before quantity
- important and urgent tasks
- self-written/initial use cases/goals are not important
use cases update

try the best to finish the thesis until end of june, in the worst case it can take a little longer

DB layout
- if (and when) it was fully done no responsible person until now -> Christophs topic now
18.6. live meeting
open questions
- icons
- avoiding float: roundig? could lead to visual glitches. We would prefer integers
- state: year->objects idea: group objects acording to visible and invisible and return both from the api. the visibility is calculated using the start_date and end_date of the elements. same calculation happens when the timeline is used in the frontend
Changelogs
sprint plan
outlook

Changelogs

Please push progress important changes devs should know, e.g. decisions, in items with syntax - change _(Your Name)_ below:

db schemata are merged but might have to be reworked when implementing the gamification use cases

plant search fixes: - no results when clicking search fixed - search was too sensitive - search splits query in substrings and ranks the results given substring matches

new documentation for full text search

use case for full text search should be changed according to current implementation

missing german names: good example of first issue

use priority sorter in jenkins

documentation of architecture

new Nextcloud instance is done

Outlook

Focus Meetings https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/20
Vote for live meeting https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/21
Get current use case (UC) done
Talk to buddy: live meeting ride sharing
Add some text for your thesis in submissions
Push at least a short Changelog to the branch meeting_notes/13.06.2023 (new syntax, see below)
FLOSS issues
Update sprint plan
Do at least 8 reviews of other PRs in main repo or submissions
Read architecture (already merged) available as mdbook, see main README.md Part II
Nextcloud testing

Next Tasks

Felix: emails, cargo, (mdbook deployment, pre-commit)
Moritz: UC plant search, UC base layer with fixed scale in frontend with NC images, seed/map search in frontend
Gabriel: API+DB for plants, UC auth, UC map search, Plant layer: relations
Lukas: keycloak broken, PostGIS, docu infrastructure
Thorben: API+DB for plants+maps, UC map creation, membership application
Samuel: landing page: (1) 2x chat msg, (2) chat window (3) gallery, components documentation, NC strukturen (circles, gruppen)
Christoph: review DB
Paul: collaborate, plant UC, (time line UC)
Yvonne: Plant Relations
Markus: end-user docu

Individual Tasks

Gabriel, Christoph, Thorben and Paul: discuss and implement Pauls proposal for PlantLayer API

Felix: - setup smtp - improve pipeline efficiency Moritz: - finish plant search - finish base layer: - database integration - scale - borders - include heatmap Gabriel: - PlantLayer API - BaseLayerAPI? Thorben: - small fixes in Map creation - finalize DB schema for BaseLayer - finalize DB schema for PlantLayer - continue Membership use case Samuel: - finish Nextcloud utils - split component documentation: - merge part of it - implement Photo Layer - disable pages when not logged in - lock Layers - keybindings Christoph: - review DB - concrete suggestions - read architecture Paul: - Planting Frontend - Collaboration PR - finish Plants Layer use case (without timeline)

Meeting Notes

mdbook on public url some time soon

base layer API: rotation, height + width, image url, borders?, heatmap?, scale?

Meeting 2023-06-13

Protocol by: Christoph

Attendees

Christoph
Samuel (Protokoll done)
Gabriel (Protokoll done)
Moritz (Protokoll done)
Thorben
Paul
Felix
Lukas
Giancarlo
Markus
Yvonne

Buddies

Lukas & Felix & Christoph
Giancarlo & Moritz
Gabriel & Thorben
Samuel & Paul

Tasks for Everyone

To be done until Friday 9.6.2023:

Focus Meetings https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/20
Vote for live meeting https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/21
Get current use case (UC) done
Talk to buddy: live meeting ride sharing
Add some text for your thesis in submissions
Push at least a short Changelog to the branch meeting_notes/13.06.2023
Create FLOSS issues (label: FLOSS)
Update sprint plan
Do at least 8 reviews of other PRs in main repo or submissions
Read architecture (already merged) available as mdbook, see main README.md Part II
Nextcloud testing

Previous Tasks

To be done until Friday 9.6.2023:

Thorben: API+DB for plants+maps, loading of map, membership application, UC Map creation done
Gabriel: API+DB for plants, UC auth, UC map search, (Plant layer: relations)
Samuel: landing page: (1) 2x chat msg, (2) chat window (3) gallery, components documentation, NC strukturen (circles, gruppen)
Felix: emails, cargo faster, (mdbook deployment, pre-commit)
Moritz: UC plant search, UC base layer with fixed scale in frontend with NC images, seed/map search in frontend
Lukas: keycloak broken, PostGIS, docu infrastructure, cache invalidation (service worker)
Christoph: review DB, read architecture, rework dev setup, docker compose cleanup
Paul: collaborate done, UC plant layer in progress, (time line UC)
Yvonne: Plant Relations
Markus: architecture part III

Agenda

09:00 welcome
protokoll: Christoph
take a step forward
live event
goal for Sunday: planting with seeds and relations
Changelogs
dev:
- branch off from latest master
- daily pushes/progress reports on issues
- draft PR review
- weekly report in ChangeLogs
- create follow-up issues about obvious problems before requesting my review
- package-lock.json
documentation first
have a look through architecture
- keycloak data
focus meetings: DB/API Thursday 15; Thursday 9:30
sprint plan
outlook

Changelogs

Please push progress important changes devs should know, e.g. decisions, in items with syntax - change _(Your Name)_ below:

KeyCloak: users with name test* removed, please use same nickname as in Nextcloud (Markus Raab)
Clarification: Polygon relates to map, even if it is shown in base layer. (Markus Raab)
Problem with Nextcloud CORS configuration: Nextcloud has no options to configure the allowed origins for CORS requests. There is a plugin to circumvent this problem for some APIs but this plugins is considered unsecure by a Nextcloud Spreed team member. It also doesn't work with the Nextcloud Spreed APIs. My suggestion is to implement a proxy for setting the correct CORS headers in our backend. (Samuel Daurer)
Items can now only be selected on their corresponding layers. (Samuel Daurer)
Basic chat utils for Nextcloud are introduced in PR #428 in /features/nextcloud_integration/api/chat.ts (NOTE: not working in production due to CORS issues) (Samuel Daurer)
Nextcloud image utils not working in production due to CORS issues right now (Samuel Daurer)
Map Creation now includes description, privacy settings and selecting a geographical location. (Thorben Staufer)
A new map will automatically store the creator as its owner through the user data provided by the Keycloak token (in PR #449). (Thorben Staufer)
The map overview page only shows maps created by the currently logged-in user (in PR #449). (Thorben Staufer)
Proposed a DB design for simple layers (layers that either place objects or contain a map-wide configuration) with the plants layer as an example (in PR #427). (Gabriel Kitzberger & Thorben Staufer)
Documentation about backend now in mdbook including auth and how to obtain tokens (PR #412) (Gabriel Kitzberger)
Allow for searching maps by name (PR #414) (Gabriel Kitzberger)
Send changes to the map to other connected clients via Server-Sent Events (PR #404) (Paul Buschmann & Gabriel Kitzberger)

Outlook: Tasks for Everyone

To be done until Friday 16.6.2023:

Create a PR that improves error handling (or adds assertions)
Get current use case (UC) done
Break "Talk to buddy" and "Submissions"
Push at least a short Changelog to the branch meeting_notes/20.06.2023
Update sprint plan
Do at least 8 reviews of other PRs in main repo or submissions
Read architecture available as mdbook, see main README.md Part III
Nextcloud testing and report to #422

Outlook: Next Tasks

To be done until Friday 16.6.2023:

Felix: cargo faster, make doc, (mdbook deployment, pre-commit, emails)
Gabriel: API+DB for plants (Tuesday), UC auth, UC map search, Plant layer: relations (API)
Christoph: docmentation regarding PermaplanT setup, import of relations (in scraper), review DB
Samuel: NC images: proxy&error handling, decision, (heatmap frontend), (landing page: (1) 2x chat msg, (2) chat window (3) gallery, components documentation, NC strukturen (circles, gruppen))
Moritz: UC plant search, UC base layer with fixed scale in frontend with NC images, seed/map search in frontend
Lukas: keycloak broken, PostGIS, docu infrastructure
Thorben: map loading map.tsx, API+DB for plants+maps docu, UC map creation done, (membership application)
Paul: UC plant layer, time line UC
Markus: end-user docu

Meeting Notes

Besprechung Live Treffen, Informationen in LivePermaplanTreffen.pdf
Portable Device mitnehmen, damit wir uns Permaplant in der Praxis anschauen können.
Handgroßen flachen Stein mitnehmen, falls jemand einen hat.
Ziel bis Sonntag 18.6.2023: Seedplanting umgesetzt damit wir die ersten Pflanzen platzieren können.
Besprechung Sprint
Thorben: Map creation Frontend->Backend funktioniert, Backend->Frontend fehlt noch.
Samuel: Basic Component documentation, hat dokumentiert womit er sich zurechtgefunden hat. Einige sind noch offen.
Felix: CI, trotz erwarteter Verbesserungen keine Veränderungen in den Laufzeiten festgestellt wurden. Ein Problem besteht darin, dass Cargo Daten erneut herunterlädt. Gabriel erklärte, dass dies bei Rust üblich ist, wenn man in Release baut, da es immer alles neu baut. Als Lösungsvorschlag wurde vorgeschlagen, PRs im Debug-Modus zu bauen und nur den Master im Release-Modus zu bauen. Der gesamte CI-Zyklus dauert derzeit 30 Minuten. Gabriel plant, sich das genauer anzusehen, befürchtet jedoch, dass beim Bauen im Release-Modus keine großen Verbesserungen möglich sind, möglicherweise könnte Caching helfen.
Lukas: Keylock, braucht hilfe wegen eines caching problems vom Frontendteam, Markus sagt wir sollten uns erst später damit beschäftigen, erst wenn wir eine stabile release haben, da noch nicht klar ist was die requirments sind.
Christoph: plan doc/backend/01setup.md issue fertig machen. Setup Script is outofScope, Leute sollen das system selbst aufsetzen.
Markus ist aufgefallen: Bei einen PR das man den letzten Master nimmt. Darauf achten das "The PR is rebased with current master." gilt. Draft PR sind ein Draft, wenn Markus um info gefragt wird, bitte genaue Frage stellen.
Hinweiß: Immer ganz schnell issues erzeugen, es ist verwirrend wenn etwas übrig ist. Herauszufinden wie es geht kostet viel Zeit. Klare Kommunikation was da ist, ist wichtig. Wenn es Probleme gibt, erstellt Issues.
Pause 10:05-10:10
Architecure Guidlines beachten, keine Workarounds. Bei Problemen issues erstellen.
Wir implementieren gerade 06runtime.html->planting. Toll wenn das bis Sonntag 18.6.2023 funktioniert.
Christoph soll Guidlines->Database überarbeiten.
Wie gehts weiter. Am Do können wir uns treffen wo es um DB+API geht.
Bei Terminumfragen sollen bitte alle Antworten.
Error Handling beachten, es soll keine "Silent Errors" mehr geben. User sollen wissen, wenn etwas nicht funktioniert hat, und warum. (Siehe UI guidlines)
Wegen LiveMeeting machen wir eine Woche Pause mit Buddy-System und Submissions.
Architekture ganz durchlesen für alle.
Starker Fokus auf Use Cases. Am Sonntag wollen wir pflanzen platzieren beim Live Treffen.
Solange wir das nicht haben, ist es schwierig weitere UseCases zu finden.
Felix: Schnellere Deployments wären hilfreich.
Gabriel: Plantlayer API+DB fertigbekommen, Heatmap gleicher PR?
Christoph: Scrapper DB Relations, import of relation in scrapper. RUST Code nachschauen für entites, Documentation Database schema aktuallsieren. Review machen wo änderungen sind.
Samuel: Nextcloud requests sollen in Production funktioneren. Fehler sollen angezeigt werden.
Moritz: Base Layer und Plant Search fertig machen. Ziel bis Freitag fertig machen. Es sind primär noch Detailfragen zu klären.
Thorben: Fokus: Laden der Map/Maploading.

Meeting 2023-06-20

Tasks for Everyone

To be done until Friday 16.6.2023:

Create a PR that improves error handling (or adds assertions)
Get current use case (UC) done
Break "Talk to buddy" and "Submissions"
Push at least a short Changelog to the branch meeting_notes/20.06.2023
Update sprint plan
Do at least 8 reviews of other PRs in main repo or submissions
Read already-merged architecture available as mdbook, see main README.md
Nextcloud testing and report to #422

Individual Tasks

To be done until Friday 16.6.2023:

Felix: cargo faster, make doc, (mdbook deployment, pre-commit, emails)
Gabriel: API+DB for plants (Tuesday), UC auth, UC map search, Plant layer: relations (API)
Christoph: documentation regarding PermaplanT setup, import of relations (in scraper), review DB
Samuel: NC images: proxy&error handling, NC file picker, NC decision, (landing page: (1) 2x chat msg, (2) chat window (3) gallery)
Moritz: UC plant search, UC base layer with fixed scale in frontend with NC images, seed/map search in frontend
Lukas: documentation of infrastructure
Thorben: map loading map.tsx, API+DB for plants+maps docu, UC map creation done, (membership application)
Paul: UC plant layer, time line UC
Markus: end-user docu

Attendees

Thorben
Christoph (Protokoll done)
Samuel (Protokoll done)
Gabriel (Protokoll done)
Moritz (Protokoll done)
Paul
Lukas
Markus
Yvonne

Did not attend

Felix
Giancarlo

Buddies

Lukas & Felix & Christoph
Giancarlo & Moritz
Gabriel & Thorben
Samuel & Paul

Agenda

09:00 welcome
protokoll: Thorben
welcome game: meeting, most annoying in UI?
UI:
- plants are all round
dev:
- package-lock.json workflow
- documentation first
- several (UI) fixes in one PR
- best time for reviews
- npm version v19.4.0 #395
- increment version numbers #164
architecture:
- no submit buttons -> debounce
- no 32 bit for increasing tables
- uuid for maps
focus meeting: DB/API Thursday 15; Thursday 9:30
sprint plan
outlook

Changelogs

Please push progress important changes devs should know, e.g. decisions, in items with syntax - change _(Your Name)_ below:

Moritz
- Plant Layer is ready to be Merged
- Helped Samuel Factor out Nextcloud image loading from base layer
Thorben
- Location picker in map creation only loads on button press. User can enter geo data manually without location picker.
- Map overview page navigates to map editor.
Paul
- Available seasonal seed suggestions.
- Placement of plants.
Gabriel
- Plantings + Plants Layer API (without heatmap)

Outlook: Tasks for Everyone

To be done until Friday 23.6.2023:

Get current use cases (UC) done
Talk to buddy about UI improvements
Submissions: abstract (4 sentences: context, problem, method, results) & conclusion
Push at least a short Changelog to the branch meeting_notes/27.06.2023
Update sprint plan
Do at least 8 reviews of other PRs in main repo or submissions
Read architecture part IV available as mdbook, see main README.md
add photos from meeting to Nextcloud Photos/20230618_Live_meeting

Outlook: Individual Tasks

use layer IDs
preview eher nicht
icons ein/ausblenden
layers ordnen
touch screen: on-click
text weg
on-hover
"planting" box besser high-lighten
redraw

To be done until Friday 23.6.2023:

Lukas: documentation of infrastructure, nextcloud fix, review felix, Keycloak SMTP (password reset)
Felix: cargo faster, make doc, (mdbook deployment, pre-commit, emails)
Gabriel: API+DB for plants finish, UC map search, Plant layer: relations (API), heat map, map polygon
Christoph: review DB, documentation regarding PermaplanT setup, import of relations (in scraper), import von sizes
Samuel: keybindings, NC file picker, NC decision, NC hierarchy, bug fixes pair programming, UI fixes mit Paul
Paul: UC plant layer, time line UC
Moritz: UC plant search, UC base layer with fixed scale in frontend with NC images, seed/map search in frontend
Thorben: UC map creation done, (membership application)
Markus: end-user docu

Meeting Notes

Recap of first in person meeting
Usability improvements for first beta/usability test:
- hide unused toolbar icons
- round icons for plants (SVG over raster image)
- change order of layers in list (#478)
- show all editable plant attributes (#476)
- format of english/german name of plants in search
- show preview of plant and relations while placing (icon moves with cursor on canvas and connecting lines are shown)
- Toast messages show success but errors more rarely
- Typical editor keybindings
- touch screen improvements
- title attributes on toolbar icons
- highlight plant placement mode with color
Plants areas as one entity on canvas
Scaling vs area of plants
Potential low performance of SSE with many users
Sprint plan:

Done:
- Maps connected to owning user through authentication token
- Plant API reworked and uses layer id instead of map id
- fixed a rounding error in planting coordinates while moving
Next Steps:
- Complete fix for CORS issues
- Keycloak mailing
- Documentation of infrastructure (variables, services, timeoutes)
- Complete plant/map search
- Implement relations and fill with curated data
- API for plant heatmap
- Reduce DB model to only used columns
- Automatic NC directories for maps and layers
- Improve UI and app usability
- Complete base layer
- Map edit/duplicate
- Implement Blossoms
Only push package-lock.json on deliberate package updates/additions
Increment version number on deliberate changes of package-lock.json
Edit fields should push changes seamlessly with debounce instead of submit button

Meeting 2023-06-27

Tasks for Everyone

To be done until Friday 23.6.2023:

Get current use cases (UC) done
Talk to buddy about UI improvements and look together to dev.permaplant.net
Submissions: abstract (4 sentences: context, problem, method, results) & conclusion
Push at least a short Changelog to the branch meeting_notes/27.06.2023
Update sprint plan
Do at least 8 reviews of other PRs in main repo or submissions (abstract)
Read already merged architecture part IV available as mdbook, see main README.md to build
add photos you have from meeting to Nextcloud Photos/20230618_Live_meeting

Bug squashing

Please help fixing known bugs and UI issues until Friday 23.6.2023, e.g.:

use layer IDs
preview eher nicht
icons ein/ausblenden
layers ordnen
touch screen: on-click
text weg
on-hover
"planting" box better highlighting
redraw on resizing

A big thanks to Samuel&Paul for being behind this! Please join the effort!

Individual Tasks

To be done until Friday 23.6.2023:

Lukas: documentation of infrastructure, nextcloud base URL frontend fix, review felix PR, Keycloak SMTP (password reset)
Felix: cargo faster, make doc, mdbook deployment, pre-commit, emails
Gabriel: API+DB for plants finish, UC map search, Plant layer: relations (API), heat map, map polygon API
Christoph: review DB, documentation regarding PermaplanT setup, import of relations (in scraper), import of "sizes"
Samuel: keybindings, NC file picker, NC decision, NC hierarchy, bug fixes pair programming, Bug squashing with Paul
Paul: UC plant layer, time line UC, Bug squashing with Samuel
Moritz: UC plant search, UC base layer with fixed scale in frontend with NC images, seed/map search in frontend
Thorben: UC map creation done, UC gain blossoms, (membership application)
Markus: end-user docu

Attendees

Paul
Christoph (Protokoll done)
Samuel (Protokoll done)
Gabriel (Protokoll done)
Moritz (Protokoll done)
Thorben (Protokoll done)
Adi
Felix
Giancarlo
Markus
Yvonne

not here:

Lukas

Buddies

Lukas & Felix & Adi
Moritz & Christoph
Gabriel & Thorben
Samuel & Paul

Agenda

09:00 welcome
protocol: Paul
welcome Adi
buddy talk: UI improvements
deadlines, create individual deadlines for you in README.md:
- maximum to August
- other remaining tasks
- issues (simply assign and link to assigned issues)
- UC
- text writing: introduction+goals
- fixing bugs
update authors.md
abstract (4 sentences: context, problem, method, results) & conclusion
architecture:
- minimal packages
- npm packages for testing?
- ids vs. text
- performance: avoid polling
show/increment version number: #510 daily micro-releases
new deployment www.permaplant.net
sprint plan
outlook

Outlook: Tasks for Everyone

To be done until Friday 30.6.2023:

Get current use cases (UC) done
Submissions: abstract (4 sentences: context, problem, method, results) & conclusion
Push at least a short Changelog to the branch meeting_notes/04.07.2023
Update sprint plan
create PR in submissions updating README.md with deadlines and all remaining tasks
create PR updating authors.md
Do at least 8 reviews of other PRs in main repo and submissions
Read already merged architecture part V available as mdbook, see main README.md to build

Outlook: Bug Squashing

Please help fixing known bugs and UI issues until Friday 30.6.2023

use icons for plants
use layer IDs
icons
layers order
touch screen: on-click
remove left-overs
on-hover texts
"planting" box better highlighting
redraw on resizing

In same PR:

also remove pan
tooltip not an selected plant and partly not visible and too small

New issues needed:

"hello" appears quite often -> Paul
texts: remove "Edit attributes", "Drag and drop" -> Pflanzen/Planting, "Layers" -> Ebenen; -> Moritz
layer tutorial -> Thorben

Already existing issues:

edit props -> Moritz
order of layers -> done master

Outlook: Individual Tasks

To be done until Friday 30.6.2023:

Thorben: UC map creation done, UC gain blossoms
Moritz: UC plant search, UC base layer with fixed scale in frontend with NC images, seed/map search in frontend, UC shade layer, grid
Paul: UC plant layer, time line UC
Samuel: UC photo layer, keybindings, NC file picker, NC decision, NC hierarchy, bug fixes pair programming, Bug squashing with Paul
Christoph: review DB, documentation regarding PermaplanT setup, import of relations (in scraper), import of "sizes" (alternatives UC)
Gabriel: business logic: plant relations, API+DB for plants finish, UC map search, Plant layer: relations (API), heat map, map polygon API
Adi: npm doc, mdbook deployment, (versioning)
Felix: pre-commit, emails
Markus: release
Lukas: documentation of infrastructure

Changelogs

Please push progress important changes devs should know, e.g. decisions, in items with syntax - change _(Your Name)_ below:

Moved to doc/CHANGELOG.md

Meeting Notes

short game with statements about other team members
thesis should be done at the latest until August (end of term)
UI improvements:
tooltip should be bigger and not overlap the mouse cursor (ideally -> scale dependent)
tooltip does not work if plant is selected
icons for plants
debug grid (every 10 cm a point or fine line)
change plant default size (30 cm)
slider handle maybe more prominent? (vertical dots)
Adi will look at the test strategy
important use cases should be tested end-to-end (move plant, add plant, ...)
first e2e test (plant search and check results)
thesis: free writing: write per hand what comes into mind -> refactor
changelog:
in its own file? -> yes (commit together with the PR)
readme in submissions:
specify final deadline (latest 31 august)
list all tasks to finish thesis

Meeting 2023-07-04

Tasks for Everyone

To be done until Friday 30.6.2023:

Get current use cases (UC) done
Submissions submit&2x review: abstract (4 sentences: context, problem, method, results) & conclusion (or TISS abstract)
Update sprint plan
Create PR in submissions updating README.md with deadlines and all remaining tasks
Create PR updating doc/authors.md
Do at least 6 reviews of other PRs in main repo
Read already-merged architecture part V available as mdbook, see main README.md to build

Bug Squashing

Please help fixing known bugs and UI issues until Friday 30.6.2023

In same PR:

also remove pan
tooltip not an selected plant and partly not visible and too small

New issues needed:

"hello" appears quite often -> Paul
texts: remove "Edit attributes", "Drag and drop" -> Pflanzen/Planting, "Layers" -> Ebenen; -> Moritz
layer tutorial -> Thorben

Individual Tasks

To be done until Friday 30.6.2023:

Thorben: UC map creation done, UC gain blossoms
Paul: UC plant layer, UC time line
Samuel: NC file picker, NC decision, NC hierarchy, UC photo layer
Lukas: documentation of infrastructure
Adi: npm doc, mdbook deployment, (versioning)
Felix:
Markus: release
Christoph: review DB, documentation regarding PermaplanT setup, import of relations (in scraper), import of "sizes" (alternatives UC)
Gabriel: business logic: heat map, plant relations, API+DB for plants finish, UC map search, Plant layer: relations (API), map polygon API
Moritz: edit plant properties, grid 10Pixel/10cm, finish UC plant search, UC base layer with fixed scale in frontend with NC images, seed/map search in frontend, UC shade layer

Attendees

Felix
Paul (Protokoll done)
Samuel (Protokoll done)
Thorben (Protokoll done)
Adi
Giancarlo
Markus
Yvonne
Lukas

Cannot come:

Gabriel (Protokoll done)
Moritz (Protokoll done)
Christoph (Protokoll done)

Buddies

Lukas & Felix & Adi
Moritz & Christoph
Gabriel & Thorben
Samuel & Paul

Agenda

09:00 welcome
protocol: Felix
Elevator Pitch what you do
case study: use real data: base map, plantings, ...
technicalities:
- matrix vs. image II (we use PNG)
- versioning
- test strategy: test protocol for getting UC done
- dev workflow, self-reflection: get more efficient
- Docker compose?
- use random lines in Changelog
sprint plan
outlook
netidee

Outlook: Tasks for Everyone

To be done until Friday 7.7.2023:

Get current use cases (UC) done
Submissions submit&2x review: intro & transitions
buddy talk: case study
Update sprint plan
Do at least 6 reviews of other PRs in main repo
Read Test Strategy and update of DoD

Outlook: User Study

Please help fixing known bugs and blocking issues for user study until Friday 7.7.2023

https://github.com/ElektraInitiative/PermaplanT/milestone/4

#151 Personifying Error Messages -> Thorben
#570 improve texts (remove "Edit attributes", "Drag and drop" -> Pflanzen/Planting, "Layers" -> Ebenen) -> Thorben
#547 Edit Planting's Dates in Sidebar
#541 plant icons shine through
plantings: mouse partially over tooltip -> Paul
labels for active layer via toolbar, "tags" icon -> Samuel
eraser/trash -> Samuel
nicht proportionales resize verbieten

Outlook: Individual Tasks

To be done until Friday 7.7.2023:

Thorben: UC map creation done, UC gain blossoms
Paul: UC time line, UC plant layer (relations&heatmap)
Samuel: base layer persist, NC file picker, NC hierarchy, UC photo layer, CORS
Adi: #504 frontend BASE_URL, cargo build, (versioning)
Felix:
Markus: netidee
Lukas: documentation of infrastructure, CORS
Gabriel: business logic: heat map, plant relations, API+DB for plants finish, UC map search, Plant layer: relations (API), map polygon API
Christoph: review DB, documentation regarding PermaplanT setup, import of relations (in scraper), import of "sizes" (alternatives UC)
Moritz: edit plant properties, grid 10Pixel/10cm, finish UC plant search, UC base layer with fixed scale in frontend with NC images, seed/map search in frontend, UC shade layer

Protocol:

-show us of programmed code, with real data -shared dir 'Biology/Template_Map.jpg' for example with real data -everyone build own map in PermaplanT -Thorben check text in PermaplanT -Samuel change icons of plants

-protocl for tests of implementations -thesis focus on question, not technical implementation

Meeting 2023-07-11

Tasks for Everyone

To be done until Friday 7.7.2023:

Read Test Strategy and update of DoD
Get current use cases (UC) done
Submit&2x review Submissions : intro & transitions
Buddy talk: case study
Update sprint plan
Do at least 6 reviews of other PRs in main repo

User Study

Please help fixing known bugs and blocking issues for user study until Friday 7.7.2023

https://github.com/ElektraInitiative/PermaplanT/milestone/4

#151 Personifying Error Messages -> Thorben
#570 improve texts (remove "Edit attributes", "Drag and drop" -> Pflanzen/Planting, "Layers" -> Ebenen) -> Thorben
#547 Edit Planting's Dates in Sidebar
#541 plant icons shine through
plantings: mouse partially over tooltip -> Paul
labels for active layer via toolbar, "tags" icon -> Samuel
eraser/trash -> Samuel
disallow non-proportional resize -> Paul

Individual Tasks

To be done until Friday 7.7.2023:

Thorben: UC map creation done, UC gain blossoms
Paul: UC time line, UC plant layer (relations&heatmap)
Samuel: base layer persistency, CORS, NC file picker, NC hierarchy, (UC photo layer)
Adi: #504 frontend BASE_URL, cargo build, (versioning), various tasks
Lukas: documentation of infrastructure, CORS
Gabriel: base map API, heat map API, plant relations, API+DB for plants finish, UC map search, Plant layer: relations (API), map polygon API
Christoph: review DB, documentation regarding PermaplanT setup, import of relations (in scraper), import of "sizes" (alternatives UC)
Moritz: edit plant properties, grid 10Pixel/10cm, finish UC plant search, UC base layer with fixed scale in frontend with NC images, seed/map search in frontend, UC shade layer
Markus: netidee
Yvonne: netidee

Attendees

Adi
Paul (Protokoll ok)
Thorben (Protokoll ok)
Gabriel (Protokoll ok)
Moritz (Protokoll ok)
Christoph (Protokoll ok)
Markus
Yvonne

Holidays:

Samuel (Protokoll ok)

Not here:

Lukas
Felix (Protokoll ok)
Giancarlo

Buddies

Lukas & Felix
Moritz & Christoph
Gabriel & Thorben
Adi & Paul

Agenda

PermaplanT

09:00 welcome
protocol: Adi
tell someone how to improve and what was done great
weekend goal: do case study
Samuel Holidays Buddies
weekly releases
weekly submissions
sprint plan
milestone plan
outlook

Outlook: Tasks for Everyone

To be done until Friday 18.7.2023:

Fix remaining problems in https://github.com/ElektraInitiative/PermaplanT/milestone/4
Do Case Study with PermaplanT
Write in submissions about your case study (as contribution, with screenshot)
For extra meetings in July: https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/22
Get current use cases (UC) done
Buddy talk: case study
Update sprint plan
Do at least 8 reviews of PRs in main repo or submissions

Outlook: Individual Tasks

To be done until Friday 18.7.2023:

Thorben: UC gain blossoms done
Paul: UC time line done, UC plant layer done relations, edit plant properties (heatmap)
Moritz: UC base layer with manual fixed scale in frontend with NC images, NC file picker, grid 10pixel/10cm (UC shade layer)
Gabriel: base map API, API+DB for plants finish, UC map search, Plant layer: relations (API), map polygon API, Lukas Doku?
Lukas: documentation of infrastructure
Adi: improve CI, smoke test
Christoph: review DB, import of relations (in scraper), documentation regarding PermaplanT setup, (import of "sizes") (alternatives UC), (squashing)
Markus: release
Yvonne: case study

Holidays:

Samuel: NC hierarchy, (UC photo layer)

Meeting Notes

Feedbackrunde: Gabriel: Lob an Paul, gute Ideen im Frontend und Backend(SSE). Paul: Feedback an Thorben, gute Arbeit im Frontend. Thorben: Feedback an Adi, schnell eingelebt. Adi: Lob an Moritz für das Testprotokoll. Moritz: Positives Feedback an Christoph.

Neue Buddies: Paul & Adi Dieses Wochende letzten fixes. PR's im Wochentakt mergen. Nicht zu lang offen lassen. Christoph & Adi wöchentlich was schreiben (Case study).

Weekly Recap: Markus viel mit Netidee beschäftigt. Moritz war auf Urlaub und krank :/. Thorben UI/UX arbeiten (hover tooltip, duplicate button, User sichtbare texte, Toast messages vereinheitlicht) Paul UI improvements und bug fixes. Konva performance probleme. Graue Linien entfernen, könnte die Performance verbessern. Gabriel: Version, cronjobs(cascade delete?), heatmap. Adi: Version, cargo build beschäftigt, kleine Pipeline improvements. Christoph: Datenbank layout, ER diagramm.

Fokus: Thorben -> Blossoms Paul -> Timeline, Plant layer Moritz -> Offene PR's abschließen. Grid->Layer scaling Paul -> Heatmap < Plant picker Gabriel -> Alles durchtesten, abschließen bis 16.07, CRUD interface baselayer + Protokoll Adi -> Tests und buildtime improvement Christoph -> DB tables, plant name formatting, plant labels.

Meeting 2023-07-18

Tasks for Everyone

To be done until Friday 14.7.2023:

Fix remaining problems in https://github.com/ElektraInitiative/PermaplanT/milestone/4
Rebase PRs due to 0.2.2 release, see Changelog
Do Case Study with PermaplanT
Write in submissions about your case study (as contribution, with screenshot)
Vote for extra meetings in July: https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/22
Get current use cases (UC) done
Buddy talk: case study
Update sprint plan
Do at least 8 reviews of PRs in main repo or submissions
Add your holidays in "PermaplanT" calendar (Nextcloud)

Individual Tasks

To be done until Friday 14.7.2023:

Thorben: UC gain blossoms done
Paul: UC time line done, UC plant layer done relations, edit plant properties, (heatmap)
Moritz: UC base layer with manual fixed scale in frontend with NC images, NC file picker, grid 10pixel/10cm (UC shade layer: frontend)
Gabriel: shade+base layer endpoints, cleanup/tests: base map API, API+DB for plants finish, UC map search, Plant layer: relations (API), map polygon API, Lukas Doku?
Lukas: documentation of infrastructure especially PermaplanT setup
Adi: improve CI, decision of E2E, smoke test
Christoph: review DB, import of relations (in scraper), various PRs+issues, including documentation regarding PermaplanT setup, (import of "sizes") (alternatives UC), (squashing)
Markus: release
Yvonne: case study

Holidays:

Samuel: NC hierarchy, (UC photo layer)

Attendees

Gabriel (Protokoll)
Paul
Thorben
Adi
Moritz
Christoph
Markus
Yvonne

Holidays:

Samuel (Protokoll ok)
Lukas
Giancarlo

Buddies

Lukas & Felix
Moritz & Christoph
Gabriel & Thorben
Adi & Paul

Agenda

PermaplanT

09:00 welcome
protocol: Lukas
carry-on PermaplanT
case study
user study
DoD UC
Test Protocol
get all PRs merged
weekly releases: 0.2.2 released, see Changelog
sprint plan
milestone plan
outlook

Outlook: Tasks for Everyone

To be done until Friday 21.7.2023:

Manual testing for done UC
Fix left-overs in https://github.com/ElektraInitiative/PermaplanT/milestone/4 and get current use cases (UC) done
Write in submissions about your case study (as contribution, with screenshot)
Update sprint plan
Do at least 8 reviews of PRs in main repo or submissions

Outlook: Individual Tasks

To be done until Friday 21.7.2023:

Thorben: UC gain blossoms done, User Study Preparations (privacy page: data usage+gets lost)
Paul: UC time line done, UC plant layer done relations, read-only, Arbeit schreiben
Moritz: UC base layer, NC file picker, grid, debouncing, open PRs merging
Gabriel:Lukas Logging Doku, preparation for squash, shade layer, docu+testprotocol for heatmap
Lukas: documentation of infrastructure especially PermaplanT setup
Adi: improve CI, decision of E2E, smoke test, help for release
Christoph: labels+formatting of plant names, import of relations (in scraper), squashing (with import of "sizes"), review DB
Markus: release
Yvonne: case study

Holidays:

Samuel: NC hierarchy, (UC photo layer)

Meeting Notes

Thorben User-Study:

Introduction
Explain Layers
- Base Layer
- Plant Layer (including explanation of seeds, maybe undo-redo, maybe toolbar instead)

Read doc/usecases/README.md.

Usecase is done iff it includes documentation, closed issues, changelog, test protocol (with links from usecase to testprotocol), moved to 'done'

Testing protocol

New tests should be added to doc/tests/manual/protocol.md
Tests in protocol.md should be simple and short
When tests are executed (e.g before release) create a new report in doc/tests/manual/reports
Write a report (inmanual/reports) about your test cases.
Reports can include more detailed explanations

Meeting 2023-07-25

Tasks for Everyone

To be done until Friday 21.7.2023:

Manual testing for done UCs
Fix left-overs in https://github.com/ElektraInitiative/PermaplanT/milestone/4 and get current use cases (UC) done
Write in submissions about your case study
Update sprint plan
Do at least 8 reviews of PRs in main repo or submissions

Individual Tasks

To be done until Friday 21.7.2023:

Thorben: UC gain blossoms done, User Study Preparations (privacy page)
Paul: UC time line done, UC plant layer done relations, read-only, Arbeit schreiben
Moritz: UC base layer, NC file picker, grid, debouncing, open PRs prepare for merging
Gabriel: Lukas Logging Doku, preparation for squash, shade layer, docu+testprotocol for heatmap
Lukas: documentation of infrastructure especially PermaplanT setup
Adi: improve CI, decision of E2E, smoke test, help for release
Christoph: labels+formatting of plant names, import of relations (in scraper), squashing (with import of "sizes"), review DB
Markus: release
Yvonne: case study
(Samuel: NC hierarchy, UC photo layer)

Attendees

Gabriel (Protokoll done)
Thorben
Adi
Moritz
Christoph
Markus
Yvonne

Cannot attend:

Paul

Holidays:

Samuel
Lukas
Giancarlo

Buddies

Moritz & Christoph
Gabriel & Thorben
Adi & Paul

Agenda

PermaplanT

09:00 welcome
protocol: Thorben
submissions:
- review more texts
- self-merge PRs
- American English vs. British English
- related work: "uniqueness", compare with others
Entwicklung:
- richtige Einstellung: keine Arbeit als lästig deklarieren
- richtige Anstrengung: nicht zu viel (anspannung), aber auch nicht zu wenig (täglich weitermachen)
further points to consider for every PR:
- migrations should not remove any data and should be compatible from now on
- introduction tour might need updates
Abschluss Code Reading
case study
user study
weekly releases: 0.3.0 released, see Changelog
sprint plan
milestone plan
outlook
warm shower

Outlook: Tasks for Everyone

To be done until Friday 28.7.2023:

Fix left-overs in https://github.com/ElektraInitiative/PermaplanT/milestone/4 and get current use cases (UC) done
Write one page in submissions
Update sprint plan
Do at least 8 reviews of PRs in main repo or submissions

Outlook: Individual Tasks

To be done until Friday 28.7.2023:

entf, labels?
Adi: manual tests, help for release
Thorben: intro tour done, User Study Preparations
Paul: read-only, Arbeit schreiben
Moritz: various fixes, debouncing, documentation, (open PRs prepare for merging)
Gabriel: preparation for squash, shade layer, docu+testprotocol for heatmap
Markus: release
Yvonne: sizes of plants
Lukas: documentation of infrastructure especially PermaplanT setup
(Christoph: sizes of plants, review DB)
(Samuel: NC hierarchy, UC photo layer)

Meeting Notes

Thesis:
- British or American english, not mixed (American preferred)
- Related work should showcase differences/what you did different
Release of 3.0 (hopefully) today
- data should be persistent going forward
- Heatmap and Introduction Tour kept as WiP
Final talk with code reading before graduation
Changelog:
- map editor has now a grid layer
- Base Layer connected to backend
- file picker for background image on Base Layer
- migrations are squashed and sanitized
- various documentation improvements and bug fixes

Meeting 2023-07-31

Tasks for Everyone

To be done until Monday 31.7.2023:

Please vote https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/24
Help with release 0.3.1 https://github.com/ElektraInitiative/PermaplanT/issues/740
Fix left-overs https://github.com/ElektraInitiative/PermaplanT/milestone/4

To be done until Friday 28.7.2023:

Get current use cases (UC) done
Write one page in submissions
Update sprint plan
Do at least 8 reviews of PRs in main repo or submissions

Individual Tasks

To be done until Friday 28.7.2023:

Adi: manual+automatic tests
Thorben: intro tour done, User Study done
Gabriel: shade layer, docu+testprotocol for heatmap
Paul: read-only, Arbeit schreiben
Moritz: various fixes, debouncing, documentation, (open PRs prepare for merging)
Markus: release
Yvonne: sizes of plants
Lukas: documentation of infrastructure especially PermaplanT setup
(Christoph: review DB, sizes of plants)
(Samuel: NC hierarchy, UC photo layer)

Attendees

Paul
Adi
Moritz
Christoph
Markus
Yvonne

Holidays:

Samuel
Giancarlo

Buddies

Adi & Paul
Moritz & Christoph

Agenda

PermaplanT

09:00 welcome
protocol: Paul
Wo stecke ich gerade?
separates Treffen: Biologie
Schreibtreffen
thesis anschauen?
Abschluss:
- thesis (matrnr, study code, title+abstract EN+DE)
- Code Reading
- community: reviews, documentation, helped others
case study
user study
lessions learned of release & manual testing
- release process
- testing process
- security process
- regression tests
- git repo für scraper/data
- file per use case for testing?
downtime of build server and www.permaplant.net on Thursday, 3rd of August, 19:00-20:00.
projects
- 185.A28 PR Project in Computer Science 1 4.0h, 6.0EC
- 185.A29 PR Project in Computer Science 2 4.0h, 6.0EC
unify debouncing
update release todos
0.3.0 released, see Changelog
weekly releases: 0.3.1 to be released today 31.07.2023
sprint plan
outlook

Outlook: Tasks for Everyone

To be done until Wednesday 2.8.2023:

Please vote https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/24
Help with release 0.3.1 https://github.com/ElektraInitiative/PermaplanT/issues/740
Fix left-overs https://github.com/ElektraInitiative/PermaplanT/milestone/4

To be done until Friday 4.8.2023:

Get current use cases (UC) done
Write one page in submissions
Update sprint plan
Do at least 8 reviews of PRs in main repo or submissions

Individual Tasks

To be done until Friday 4.8.2023:

Paul: read-only, Arbeit schreiben
Adi: manual+automatic tests
Moritz: heatmap, documentation
Thorben: intro tour done, User Study done
Lukas: unify PermaplanT setup
Gabriel: shade layer, docu+testprotocol for heatmap
Christoph: DB docu update, improve scraper, deutsche Namen, hierarchy
Samuel: NC hierarchy, share base layer
Markus: release
Yvonne:

Meeting Notes

Größte Schwierigkeiten zur Zeit: Thorben: Einführungs-Tour Samuel: Will mit schriftlicher Arbeit fertig werden Paul: schriftliche Arbeit, offline mode Christoph: Hierachie der Daten, biologische Seite besser verstehen Adi: frontend testing, keine größeren Schwierigkeiten

Related Work: verallgemeinern wenn zu speziellem thema wenig literatur vorhanden ist.

unison file synchronizer (phd thesis)

Thesis struktur: case study vielleicht in intro nach art der benchmarks aufteilen

methode
resultat
diskussion

user study: 2 teilnehmer bis jetzt ablauf: - karte erstellen - tour durchgehen (tour wird gerne unabsichtlich abgebrochen) - 20 minuten freestyle positives feedback

mehr regession tests vlt e2e tests auf jeden fall test protokoll

Meeting 2023-08-08

Tasks for Everyone

To be done until Wednesday 2.8.2023:

Help with release 0.3.1 https://github.com/ElektraInitiative/PermaplanT/issues/740
Fix left-overs https://github.com/ElektraInitiative/PermaplanT/milestone/4
Please vote for code readings etc. https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/24
Write if interested in projects:
- projekt neu 194.145 and 194.146
- 185.A28 PR Project in Computer Science 1 4.0h, 6.0EC
- 185.A29 PR Project in Computer Science 2 4.0h, 6.0EC

To be done until Friday 4.8.2023:

Get current use cases (UC) done
Write at least one page in submissions
Update sprint plan
Do at least 8 reviews of PRs in main repo or submissions

Individual Tasks

To be done until Friday 4.8.2023:

Paul: read-only, Arbeit schreiben
Adi: manual+automatic tests
Moritz: heatmap, documentation
Thorben: intro tour done, User Study done
Lukas: unify PermaplanT setup
Gabriel: shade layer, case study+docu+testprotocol for heatmap
Christoph: DB docu update, improve scraper, deutsche Namen, hierarchy
Samuel: NC hierarchy, (share) base layer
Markus: release
Yvonne:

Attendees

Samuel (Protocol done)
Adi
Moritz
Christoph
Markus

Buddies

Adi & Samuel (NC fixes)
Moritz & Christoph (security/performance testing strategy)

Agenda

PermaplanT

09:00 welcome
protocol: Samuel
feedback/lessions learned
- duplicates
- bureaucracy
Gabriel fertig
case study
projekt neu 194.145 and 194.146
Mo vs Di Treffen?
code quality within PRs, identified features and usability improvements in follow-up issues
always write/update/ask implementation issues before starting working on them
update release todos
0.3.1 and 0.3.2 released, see Changelog
sprint plan
outlook

Outlook: Tasks for Everyone

To be done until Friday 11.8.2023:

Get current use cases (UC) done
Write at least one page in submissions
Update doc/authors.md and avatar in NC nextcloud/Public/Avatars/
Write if interested in projects:
- projekt neu 194.145 and 194.146
- 185.A28 PR Project in Computer Science 1 4.0h, 6.0EC
- 185.A29 PR Project in Computer Science 2 4.0h, 6.0EC
Update sprint plan
Do in total ~80 reviews of PRs in main repo or submissions

Outlook: Individual Tasks

To be done until Friday 11.8.2023:

Adi: NC config, finish Makefile, modularization, create/cleanup/prior CI issues
Moritz: documentation, seeds, shade, polygon, (base layer)
Christoph: plants hierarchy+overrides, security/keycloak roles strategy
Samuel: NC hierarchy, (share) base layer, cleanup issues/PRs

Meeting Notes

Feedback: - same/conflicting information at different locations

Project: Look at new PR courses: 194.145 and 194.146 Project is work hour focused

What should be in PR what in follow up issues: - code quality issues or missing documentation in PR - functional extensions can be in follow up issues Guideline: repository should be in a better state after each PR

Write issues with specification before starting to work on it. Update issue description and ask if it is still correct/relevant before starting to work on it.

Hierarchy Implementation Proposal accepted.

Hierarchy extension: Plant icon name in database for different hierarchy levels. Frontend gets the icon name it should request from Nextcloud.

Meeting 2023-08-15

Tasks for Everyone

To be done until Friday 11.8.2023:

Get current use cases (UC) done
Write at least one page in submissions
Update doc/authors.md and avatar in NC nextcloud/Public/Avatars/
Write to Markus if interested in projects:
- projekt neu 194.145 and 194.146
- alt: 185.A28 PR Project in Computer Science 1 4.0h, 6.0EC
- alt: 185.A29 PR Project in Computer Science 2 4.0h, 6.0EC
Update sprint plan
Do in total ~80 reviews of PRs in main repo or submissions

Individual Tasks

To be done until Friday 11.8.2023:

Adi: NC config, finish Makefile, modularization, create/cleanup/prior CI issues
Samuel: NC hierarchy, (share) base layer, cleanup issues/PRs
Moritz: documentation, seeds, shade, polygon, (base layer)
Christoph: plants hierarchy+overrides, security/keycloak roles strategy

Attendees

Samuel (Protocol done)
Adi
Moritz
Christoph K. (Chris)
Markus
Yvonne
Jannis
Christoph N.

Buddies

Adi & Samuel (NC fixes)
Moritz & Christoph (security/performance testing strategy)
Jannis & Christoph

Agenda

PermaplanT

09:00 welcome Jannis und Christoph N.
plant hierarchy
protocol: Adi
expectations on thesis and teamwork
- Progress, Weekly Tasks & Surprises (Delay&Be faster)
- Quality&Code&Teamwork matters most
- Paper: less is more
how to finish thesis:
- do all your tasks in good quality (don't create a personal backlog)
- create issues etc. early, think ahead of next tasks (critical chain)
- be a team-player, review others work, document for others and yourself (including Forschungstagebuch)
- and never forget your health comes first
how to write a paper
- RQs
- related work
- define terms (first in glossary)
English scientific technical text:
- avoid synonyms
- active voice (We..)
- short sentences
- avoid modal verbs (can, may, might), for probability see https://github.com/zonination/perceptions
sprint plan
outlook

Outlook: Tasks for Everyone

To be done until Friday 18.8.2023:

Get current use cases (UC) done
Update submission repo to be like described in submissions' README.md using PRs for reviewable parts (push moving of files etc.)
Update doc/authors.md and avatar in NC nextcloud/Public/Avatars/
Update sprint plan
Do reviews of PRs in main repo and submissions

Outlook: Individual Tasks

To be done until Friday 18.8.2023:

Jannis: opensesame read from chat
Felix: opensesame get it running & case study
Adi: (starting with project) NC config, E2E coding guidelines, finish Makefile, create/cleanup/prior CI issues
Moritz: UC done (grid), seeds UC done, (polygon, base layer, shade)
Chris: plants hierarchy+overrides, (security/keycloak roles)
Samuel: PDF, UC done (visibility, login), NC hierarchy, (share) base layer, cleanup issues/PRs
Thorben: final submission thesis
Christoph: various small usability issues, copy&paste UC

Meeting Notes

Hierachy implementation

Namen von Pflanzen
Genus Species Varity Cultivar
Brassica oleracea alba 'Filderkraut'
Genus Species Cultivar
Cucumis sativus 'Qualitas'
Genus Species
Vaccinium Patriot

For the new Hierachy implementation, a plant can be saved in any of these tables: species, variety and cultivar. It depends on their name. To determine the entry for the species, variety, we perform a majority analysis of our data to identify the most common data entries.

Bachelorarbeit - Critical Chains

Kurzes Paper, Qualität und Code sind wichtiger (auch Teamwork/Reviews). Critical Chain -> Vorausplanen. Sie sind unvermeidbar und müssen anfangen zu laufen, denn sie benötigen fixe Zeit. Christoph Kraus: Research Question, Security Strategie Moritz: Implementierung Samuel: Kleine rust critical chain Felix: Hardware, Feasibility statt Benchmark

How to Bachelorarbeit

Die Research Questions zu beantworten ist das Ziel des Papers. Introduction/Related work sind Nebenschauplätze. See https://github.com/ElektraInitiative/submissions/blob/master/unterlagen/recommended_writing_order.md

Terminologie wichtig einzuhalten und zu definieren. Im Rahmen einer Bachelorarbeit eher restriktiv. Kritisch: Research Questions -> Method -> Result Unkritisch: Abstract | Introduction | Conclusion |

Objektives und Subjektives klar trennen.

Scientific:

Methode -> Algorithmus, wie sieht die Vorgehensweise der Arbeit aus. Wie werden Resultate generiert
Results -> objektive beschreibungen, keine analyse, keine schlussfolgerung. Nur blanke daten, die von anderen reproduzierbar/beobachtbar sind.
Conclusion/Discussion -> Eigene Meinung

Technical

Eindeutig, klar und pregnant ausdrücken.
Keine Synonyme, klare Terminologie.
Meistens Hauptwörter.
Active Voice "we".
Kurze Sätze, keine modalen Wörter (U ~~can~~ see, U see).

Teamwork (20%)

Dokumentation für andere (auch Vorteil für einen selber später)
Reviews schreiben

Forschungstagebuch effektiv für das Schreiben der Arbeit. Gesundheit > Forschen

Weekly Recap

Adi: CI/Testing - E2E Dokus
Samuel: (verpasst, war am schreiben)
Moritz: Älteres Feature fertig gemacht (Seeds edit/löschen)
Christoph Kraus: Scraper/Datenbank/Security(Keycloak)

Meeting 2023-08-22

Tasks for Everyone

To be done until Friday 18.8.2023:

Get current use cases (UC) done
Update submission repo to be like described in submissions' README.md using PRs for reviewable parts (push moving of files etc.)
Update doc/authors.md and avatar in NC nextcloud/Public/Avatars/
Update sprint plan
Do reviews of PRs in main repo and submissions

Individual Tasks

To be done until Friday 18.8.2023:

Jannis: opensesame read from chat
Felix: opensesame get it running & case study
Adi: (starting with project) NC config, E2E coding guidelines, finish Makefile, create/cleanup/prior CI issues
Moritz: UC done (grid), seeds UC done, (polygon, base layer, shade)
Chris: plants hierarchy+overrides, (security/keycloak roles)
Christoph: fix various small usability issues, copy&paste UC
Samuel: (share) base layer, cleanup issues/PRs
Thorben: final submission thesis, UC done, NC folder with user study data
Paul: final submission thesis, read-only offline PR

Attendees

Adi (Protocol done)
Moritz
Christoph K. (Chris)
Christoph N.
Jannis
Markus
Yvonne

Buddies

Moritz & Chris
Jannis & Christoph
Adi & Felix

Agenda

PermaplanT

09:00 welcome
buddy talk
Protocol: Moritz
Paul, Thorben, Samuel and Adi finished their thesis!
English text:
- moodchanger
- FLOSS https://www.gnu.org/philosophy/floss-and-foss.en.html
- introduce terms (italics)
- project<->initiative
- Chapter~X
- do more reviews, that way you learn much more ways to express yourself
outlook is commitment every week:
- your promise to be done
- must be clear to us both
- so that you don't delay your finish
- about 8 reviews
- daily pushes/issues/...
opensesame:
- deb from build server
- async refactor
more testing:
- scenarios in Gherkin
- start with writing scenarios
- integration tests (using https://mswjs.io/), e.g. writing a debounce test
- snap should test whole layers+pages (not individual components)
- E2E tests
Release:
- ready to merge
- rc-blocker issues
- release will be done by Adi
guidelines:
- use tailwind CSS linter (extension)
- only use toasts for errors
sprint plan
outlook

Outlook: Tasks for Everyone

To be done until Friday 25.8.2023:

Please vote in https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/25
Buddy talk: Talk about your research questions
Create a PR with tests
Get current use cases (UC) done
Update sprint plan
Do reviews of PRs in main repo and submissions

Outlook: Individual Tasks

To be done until Friday 25.8.2023:

Jannis: refactor framework, opensesame read from chat, issue erstellen setup
Felix: opensesame get it running & case study
Chris: scaper fertig, plants hierarchy+relations
Moritz: selection, seeds UC done, polygon, page test, UC done (grid)
Adi: (starting with project) E2E coding guidelines, finish Makefile, Lukas Agenda
Lukas: NC (config), mdbook deployment
Christoph: fix various small usability issues, copy&paste UC

Meeting Notes

Four team members finished their thesis.

Topic for buddies this week: research questions. Common mistakes in English text: mood changers: "on the other hand" is only used in whole phrases i.e. "on the one hand -> on the other hand". Use "But", "However" or paragraphs to indicate mood changes.

Open Source and Free Software is not quite the same:

Free Software has its focus on free as-in-speech software+development (see FSF/Richard Stallman).
Open-Source Software has its focus on practical utility and advantages of free licenses in software+development (see OSI).
FLOSS, which contains both Free Software and Open-Source Software in its name, is the preferred term in scientific texts.

Shorthands: spell out the first time it is used e.g.: Free Software Foundation (FSF).

Project/Initiative: Project has a deadline, Initiatives do not.

"Figure~X" is always spelled with an Initial capital letter when it used for referencing a specific figure "X".

Meeting 2023-08-28

The meeting will be on Monday 9:00.

Tasks for Everyone

To be done until Friday 25.8.2023:

Please give your vote in https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/25
Buddy talk: Talk about your research questions
Create a PR with tests (unit, integration or E2E)
Get current use cases (UC) done
Update sprint plan
Do reviews of PRs in main repo and submissions

Individual Tasks

To be done until Friday 25.8.2023:

Jannis: refactor framework, opensesame read from chat, issue erstellen setup
Felix: opensesame get it running & case study
Chris: scaper fertig, plants hierarchy+relations
Moritz: selection, seeds UC done, polygon, page test, UC done (grid)
Adi: (starting with project) E2E coding guidelines, finish Makefile, Lukas Agenda
Lukas: NC (config), mdbook deployment
Christoph: fix various small usability issues, copy&paste UC

Attendees

Christoph N.
Jannis
Felix
Markus
Yvonne

War nicht da:

Christoph K. (Chris)
Adi (Protocol done)
Moritz (Protocol done)

Buddies

Moritz & Chris
Jannis & Christoph
Adi & Felix

Agenda

09:00 welcome
Protocol: Christoph
buddy talk
Nextcloud app
computer/hardware
case study
read guidelines, check them in code reviews
cleanup branches or use separate repository
free writing: choose a topic, write for at least fixed 10-20 minutes.
- hand stays in movement, no deletion
- don't worry about spelling or grammar
- look forward to next time
testing decisions and strategy
first define behavior using Gherkin
3.3 release
sprint plan
outlook

Outlook: Tasks for Everyone

To be done until Wednesday 30.8.2023:

register in keycloak
submit/finalize TISS.txt (Jannis, Christoph N., evtl. Felix)
milestone update

To be done until Friday 1.9.2023:

mind. 10min free writing
Buddy talk: Talk about your case study
Get current issues, PRs and use cases (UC) done
Update sprint plan
Do reviews of PRs in main repo and submissions

Outlook: Individual Tasks

To be done until Friday 1.9.2023:

Jannis&Felix: Schnittstellenbeschreibung, refactor framework für Wetterstation+sensors+buttons, opensesame read from chat, issue erstellen setup
Christoph: fix various small usability issues, copy&paste UC
Adi: E2E tests seeds, 3.3 release, finish Makefile, Lukas Agenda, Dockerfiles vereinheitlichen
Chris: scaper fertig, plants hierarchy+relations
Moritz: selection, seeds UC done, polygon, page test, UC done (grid)
Lukas: NC (config), mdbook deployment

Meeting Notes

buddy-meeting regarding RQs
communication via Nextcloud (markus and yvonne are there) or via discord who wants to
case study: mention in the contributions that we actually used the software for something real (e.g. a plant bed in case of PermaplanT) and not just used it randomly "for fun"
updated changelog.md now has to be part of every PR
Felix: use a picture of the set-up hardware and add it to the thesis
Christoph: add decision regarding test strategy for the frontend, especially integration testing
Jannis: keycloak registration (with real name)
Christoph+Jannis: add title and working abstract for TISS
OpenSesame: things that are not statically testable have to be reviewed and manually checked

How to get text to paper

Use Free Writing as a method

write by hand
reserve a timeslot (like 10-20min) and set a countdown
most important thing is to continuously write during this period and to not delete (strike-through) anything, just continue to write
usually trying to write grammatically correct sentences is often hindering and can anyway be done afterwards (also automatically by tools)
do not write result-oriented; usually a few ideas exist afterwards anyway, though that's not the main goal of this method
this is a technique purely to get text to paper and not to find a research question
Task till next meeting: try out "Free Writing" and talk about it

Meeting 2023-09-04

Tasks for Everyone

To be done until Friday 1.9.2023:

Do minimum 10min free writing
Buddy talk: Talk about your case study
Get current issues, PRs and use cases (UC) done
Update sprint plan
Do reviews of PRs in main repo and submissions

Individual Tasks

To be done until Friday 1.9.2023:

Jannis&Felix: Schnittstellenbeschreibung, refactor framework für Wetterstation+sensors+buttons, issue erstellen setup, (opensesame read from chat)
Christoph: fix various small usability issues, copy&paste UC
Adi: E2E tests seeds, 3.3 release, finish Makefile, split pre-commit for CI, Lukas Agenda, unify Dockerfiles
Chris: scaper fertig, plants hierarchy+relations
Moritz: selection, seeds UC done, polygon, page test, UC done (grid)

To be done for Jannis and Christoph N. until Wednesday 30.8.2023:

submit/finalize TISS.txt
register in keycloak
Milestone plan update

Attendees

Chris K.
Jannis
Felix
Christoph N. (Protocol done)
Adi (Protocol done)
Moritz (Protocol done)
Markus
Yvonne

Buddies

Moritz & Chris
Jannis & Christoph
Adi & Felix

Agenda

09:00 welcome
welcome game
Protocol: Chris K.
buddy talk: case study
frontend:
- discuss usability concepts (copy&paste, multi-selection, tablet, timeline, plant relation, ...)
- locators
report about free writing
Clustering/Mindmapping
Format: Markdown/LaTeX
task issues:
- should anticipate implementation challenges
- scope/further work should be clear
- "definition of done" for UC part of task
- specify backend tasks for Jannis
progress visible only if tasks are also done
- create enough tasks to have regular progress and
- enough outlook (but not too much to not overwhelm you)
70/20/10 rule
Socrates Questioning, see unterlagen/socratic_questioning.md
3.3 release
sprint plan
outlook

Outlook: Tasks for Everyone

To be done until Friday 8.9.2023:

Submit RQs and do Socrates Questioning on your own and other RQs, see unterlagen/socratic_questioning.md
Buddy talk: Talk about your methodolgy
Get current issues, PRs and use cases (UC) done
Create/update issues as needed for future tasks
Update sprint plan
Do reviews of PRs in main repo and submissions

Outlook: Individual Tasks

To be done until Friday 8.9.2023:

Jannis&Felix: Schnittstellenbeschreibung, Ablauf bei Initialisierung und Fehler, refactor framework für buttons+Wetterstation+sensors, issue erstellen setup, opensesame read from chat
Moritz: UC done (grid), seeds UC done, seeds page test, (polygon)
Christoph: fix various small usability issues, copy&paste UC
Jannis: backend tasks durchschauen
Chris: scaper fertig, plants hierarchy+relations
Adi: E2E tests seeds, 3.3 release, finish Makefile, Lukas Agenda

Meeting Notes

Wie ist es mit unseren Buddy Talk gegangen? Buddy Talks haben nicht stattgefunden. Wir sollen uns 10 Minuten einplanen für Free Writing zur Übung. Termin ausmachen zwischen Christoph, Markus und Yvonne wegen Usability.

Weitere Methoden statt freewriting: Mindmapping Clustering

Hilfreich um relation in seinem Thema zu finden.

Arbeit in Markdown(oder anderen Tools) schreiben ist auch okay, es muss nur ein pdf für TISS sein. Siehe die Arbeit von Nursultan als Beispiel.

Erstellung von Tasks rennt noch nicht so gut. Immer bevor wir implementierungs Tasks angehen, sollen wir ein Issue erstellen, welches beschreibt wie wir es angehen wollen. Die Hauptimplementation Challenges sollen beschrieben werden. Es sollen keine zusätzlichen Sachen eingefügt werden, die nicht besprochen wurden. In-Scope bleiben, wenn notwendig eigene Issues anlegen. Gäniges Problem, sachen werden nicht ganz zu Ende gemacht, einzelne Sachen von Implementierungen fehlen noch. Man soll ein Issue mit abschließenden Tasks dazu erstellen, falls es dazu kommt. Gegenseitig Issues erstellen kann vorteilhaft sein.

Research Questions, falls wir keine haben, sollen wir uns noch überlegen. Von Sokrates gibt es eine Methode, im Submission repo (/unterlagen) gibt es dazu eine Erklärung. PRs von anderen Leuten kontrollieren und RQ evaluieren.

Bei RQ ist es wichrtig das es nicht nur eine Ja/Nein Antwort darauf gibt (offene Frage), und das es eine Methodik gibt, die diese Frage beantwortet. Mit welcher Software, mit welchen Schritten habe ich meine RQ analysiert und beantwortet. Statt einer RQ kann man auch eine Hypothese aufstellen. RQ haben sich mittlerweile etabliert. Pause für openseasam 9:51-10:05

Meeting 2023-09-11

Tasks for Everyone

To be done until Friday 8.9.2023:

Submit RQs and do Socrates Questioning on your own and other RQs, see unterlagen/socratic_questioning.md
Buddy talk: Talk about your methodology
Get current issues, PRs and use cases (UC) done
Create/update issues as needed for future tasks
Update sprint plan
Do reviews of PRs in main repo and submissions

Individual Tasks

To be done until Friday 8.9.2023:

Jannis&Felix: Schnittstellenbeschreibung, Ablauf bei Initialisierung und Fehler, refactor framework für buttons+Wetterstation+sensors, issue erstellen setup, opensesame read from chat
Moritz: UC done (grid), seeds UC done, seeds page test, (polygon)
Christoph: fix various small usability issues, copy&paste UC
Jannis: backend tasks durchschauen
Chris: scaper fertig, plants hierarchy+relations
Adi: E2E tests seeds, 3.3 release, finish Makefile, Lukas Agenda

Attendees

Jannis
Christoph N. (Protocol done)
Adi (Protocol done)
Moritz (Protocol done)
Markus
Yvonne

Did not attend:

Chris K. (Protocol done)

Buddies

Moritz & Chris
Jannis & Christoph
Adi & Felix

Agenda

09:00 welcome
word game
Protocol: Jannis
3.3 release: seeds
Buddy talk: methodology
PRs:
- quickly review+quickly fix changes
- resolve done review points
- put all reviews together in one commit
- rerequest reviews on fixes
- add # to changelog
Socrates Questioning, see unterlagen/socratic_questioning.md
use cases, behavior driven, implementation issues
sprint plan
Mon&Tue Markus not available
then a bit refactoring
outlook

Outlook: Tasks for Everyone

To be done until Friday 15.9.2023:

cloud.permaplant.net migration: copy data to keycloak auth cloud.permaplant.net account
Submit RQs and do Socrates Questioning on your own and other RQs, see unterlagen/socratic_questioning.md
Buddy talk: Talk about Reviews/PRs
Get current issues, PRs and use cases (UC) done
Create/update issues (behavior driven) as needed for future tasks
Update sprint plan
Do reviews of PRs in main repo and submissions

Outlook: Individual Tasks

To be done until Friday 15.9.2023:

Jannis&Felix: Schnittstellenbeschreibung, Ablauf bei Initialisierung und Fehler, refactor framework für buttons+Wetterstation+sensors, issue erstellen setup, opensesame read from chat
Christoph: visibilty bug, multi-select, copy&paste UC preparations
Moritz: seeds UC done, seeds page test, finish grid UC
Chris: scaper fertig, plants hierarchy+relations
Adi: E2E seeds tests, 3.3 release, finish Makefile

refactoring

Meeting Notes

Search does not work with full names => currently not urgent
difference between method and methodology not relevant for us
PR should be short-lived because they affect others, timeframe of one week, bundle suggestions logically or by reviewer
feature requests / new ideas in PRs:
- userstory / idea not clear before implementations
- not every question in a request for the current PR
- bigger changes in follow-up PR
Use Socratic Questioning to improve research questions
selection vastly improved
pending: 3 different assets folders in frontend
buddy talk: Review PR together, talk about PR experience
Make behaviour driven issues
Opensesame: bring async refactor to an exceptable state until next week, difficulties:
- libmobus / config are not sendable between threads
- signals are not implemented in tokio
- ssh needs to be tested
Either copy-paste and multiselect is needed.
Release today if no critical bug

Meeting 2023-09-18

Attendees

Adi
Moritz
Felix
Jannis
Christoph N.
Markus
Yvonne

Could not attend:

Giancarlo
Chris K.

Buddies

Moritz & Chris
Jannis & Christoph
Adi & Felix

Agenda

09:00 welcome
Permaculture Principles Part I
Protocol: Adi
Buddy talk, was methodology, will be "problem is the solution"
3.3 release done: seeds
finalize seed use case:
- seed search
- additional name everywhere
create PRs earlier to clarify updates to UC etc.
sprint plan
outlook

Tasks for Everyone

To be done until Friday 22.9.2023:

Get current issues, PRs and use cases (UC) done
Buddy talk: Talk about permaculture principle "problem is the solution"
Create/update issues (behavior driven) as needed for future tasks
submit one page of text, maybe from free writing
Update sprint plan
Do reviews of PRs in main repo and submissions

Individual Tasks

To be done until Friday 22.9.2023:

Felix: (1) Module, Initialisierung, Sender+Receiver, Schnittstellenbeschreibung ohne Fehler, Trait Send impl, method for testing (2) Shutdown&Watchdog&Fehler&Pipes overruns, finish refactor
Christoph: search improvements, multi-select UC erstellen, copy&paste UC split, usability guidelines, restore-viewing-state UC (decision: Zustand persist)
Moritz: seeds search, seeed UC done, seeds page test
Adi: E2E seeds tests, finish Makefile
Chris: scraper fertig, plants hierarchy+relations

Meeting Notes

Buddy Talk

Talk about "Problem is the Solution"

Next Goals

Connect seeds (better) with map page
- Remove seeds fold
- Two search functions (one for plants, one for seeds)
- Complete + additional names as search result for seeds
- Hover -> Complete + additional name
- Left Bar -> Complete + additional name

Continuous Integration

Push/Commit frequently so you can get feedback
Small PR's (Test-driven or Document-driven)
Request feedback from buddies

Opensesame

Modularization(all modules) + event-driven
Testing is not complete yet
What happens if the buffer/queue is full and the receiver is offline?
Name collision send

Has been done

Christoph

Search function + Frontend tests
Selection bug fixes
Copy & Paste usecase -> to doc/research
Zustand library persist

Moritz

Seed overview + bugfixes
Sqlviews in rust (Collaborate with Christoph)
Diesel queries

Adi

Release

To be done

Everyone

Thesis: One page free writing -> but submit in reworked (not free written) form

Christoph

Write use cases
Seed search functionality on plant layer (remove folding) #913

Moritz

Seed search
Search results sort by dates

Adi

Finish Seed tests
Finish makefile

Meeting 2023-09-25

Attendees

Markus
Yvonne
Daniel
Adi (protocol done)
Moritz (protocol done)

Did not attend:

Christoph N.
Chris K.
Jannis
Felix

Buddies

Moritz & Chris
Adi & Felix
Jannis & Christoph
Daniel & Adi (Beginn)

Agenda

09:00 welcome
Buddy talk, was "Problem is the Solution"
Permaculture Principles Part II
Protocol: Moritz
3.4 release, finalize seed use case:
- seed search
- additional name everywhere
sprint plan
outlook

Upcoming Meetings

Infrastructure Meetings:

26.9.2023 15:00, with Adi and Lukas
24.10.2023 15:00, additionally with Daniel and Chris

Tasks for Everyone

To be done until Friday 29.9.2023:

Get current issues, PRs and use cases (UC) done
Buddy talk: milestones, intro in PermaplanT/Submission
Create/update issues (behavior driven) as needed for future tasks
submit one page of text, maybe from free writing
Update sprint plan
Do reviews of PRs in main repo and submissions

Individual Tasks

To be done until Friday 29.9.2023:

Daniel: intro tasks, submissions, use cases
Adi: E2E seeds tests
Moritz: seeds search, seed UC done, seeds page test
Felix: (1) Module, Initialisierung, Sender+Receiver, Schnittstellenbeschreibung ohne Fehler, Trait Send impl, method for testing (2) Shutdown&Watchdog&Fehler&Pipes overruns, finish refactor
Christoph: search improvements, multi-select UC erstellen, copy&paste UC split, usability guidelines, restore-viewing-state UC (decision: Zustand persist)
Chris: scraper fertig, plants hierarchy+relations

Meeting Notes

Goal for this week: Finish and Release Seed use case. What was done last week: Christoph managed to fix a tricky Bug regarding search fields being cleared implicitly. Adi improved makefile dependencies. Moritz worked on various bugs and improvements on the seeds page.

Meeting 2023-10-02

Attendees

Markus
Yvonne
Daniel (protocol done)
Adi (protocol done)
Moritz (protocol done)
Jannis
Felix

Could not attend:

Christoph N.
Chris K.

Buddies

Moritz & Chris
Adi & Felix
Jannis & Christoph
Daniel & Jannis (Milestone)
Moritz & Adi (Locators)

Agenda

09:00 welcome: thumbs up/down
Protokol: Daniel
Buddy talk, was "milestones"
3.4 release, finalize seed use case:
- seed search
- additional name everywhere
sprint plan
outlook

Tasks for Everyone

To be done until Friday 06.10.2023:

Get current issues, PRs and use cases (UC) done
Write or implement together with buddy
Create/update issues (behavior driven) as needed for future tasks
Update sprint plan
Do reviews of PRs in main repo and submissions

Individual Tasks

To be done until Friday 06.10.2023:

Felix: Modul Dokumentation, Fehler, Schnittstellenbeschreibung mit Fehler, Shutdown&Watchdog Beschreibung, issues für sonstige Probleme
Moritz: additional name fix, seeds search, seed UC done, (refactoring)
Daniel: intro tasks, submissions, use cases, 4 issues
Adi: fix master, (E2E seeds/concurrency tests, locator guidelines)
Jannis: milestone plan, Dockerfile neues Rust, 2 first PermaplanT issues
Christoph: search improvements, multi-select UC erstellen, copy&paste UC split, usability guidelines, restore-viewing-state UC (decision: Zustand persist)
Chris: scraper fertig, plants hierarchy+relations

Meeting Notes

Milestone plans:

Daniel: has to write milestone plan for implementation and thesis
Felix: case study has to be written, everything is tested, close to finish
Jannis: wants to start with PermaplanT
Moritz: make plan for further tasks and milestones
Jannis & Daniel: will meet to talk about organisation and milestones

Tasks:

Jannis: will test new rust version, language bug for plant search
Moritz: fix names of plants, seed search
Daniel: analyse timeline usecases and refine, tasks from Github
Adi: e2e test strategy for database cleanup

Meeting 2023-10-09

Attendees

Markus
Yvonne
Daniel (protocol done)
Adi (protocol done)
Moritz (protocol done)
Christoph N.
Chris K.
Felix

Cannot attend:

Jannis

Buddies

Moritz & Chris
Adi & Felix
Jannis & Christoph
Daniel & Jannis (Milestone)
Moritz & Adi (Locators)

Agenda

09:00 welcome
case study
Protocol: Christoph N.
Buddy coding/writing sessions?
I added unterlagen/english.md for you
planning:
- How to write a milestone plan: Granularity, Realism
- also plan for unexpected: helping others, urgent tasks (broken master etc.)
- weekly tasks should be detailed
- important: regular submissions, stay on track
- submissions: always create PRs, close them soon
architecture, decisions
Priorities:
1. urgent/release critical tasks
2. get PRs merged
3. finish UC
4. start new tasks/UC
3.4 release, finalize seed use case:
- fix plant search
- release
- refactor
sprint plan
outlook

Tasks for Everyone

To be done until Friday 13.10.2023:

Read unterlagen/english.md and submit a (short) text
buddy talk: case study
Get current issues, PRs and use cases (UC) done
Create/update issues/tests (behavior driven) as needed for future tasks
Update sprint plan
Do reviews of PRs in main repo and submissions

Individual Tasks

To be done until Friday 13.10.2023:

Felix: Modul Dokumentation, Fehler, Schnittstellenbeschreibung mit Fehler, Shutdown&Watchdog Beschreibung/Drop, issues für sonstige Probleme
Moritz: additional name fix, seeds search, seed UC done, refactoring, issue seeds on the map
Daniel: create issues (backend, sql query), keybinding+notes decisions/concept, impl notes?
Christoph: UC merge, usability guidelines, PR seed search?, submission repo
Adi: help fix master, release, (E2E seeds/concurrency tests, locator guidelines)
Chris: scraper fertig, plants hierarchy+relations
Jannis: milestone plan, Dockerfile neues Rust, 2 first PermaplanT issues

Meeting Notes

Typical erros when writing the thesis are summarized in unterlagen/english.md

Milestones

should be different from the weekly plan
cornerstones should be listed like results and methods
consider a buffer due to occurences of unexpected problems
less milestones preferable
adi's experience: biggest effort was in the beginning finding the RQs and in the end revising the whole thesis
most important thing is to regularly be busy with the thesis and implementation
closing PRs is always very important
creating new leftovers from existing PRs (instead of squeezing it in) helps to finish existing PRs

Architecture and Decisions

important to identify the main components of an application/system and differentiate from details like interfaces
decisions regarding architecture are essential
solutions and guidelines is something which needs constant adaptations

General

Release critical issues and PRs have highest priority
General guideline is to first finish things instead of opening new stuff

Current issues

Frontend Restructuring

try to move svg's into src/icons folder and see how it goes
in case there is a location problem with e.g. the favicon, it is okay to have single icons in the public folder

Seed Search

(markus + yvonne) discuss and find a solution on how to best present and potentially combine the plant- and seed-search
seeds have no physical size, can be a literal seed but also a full plant; seeds simply resemble the genetical material of a plant

Meeting 2023-10-16

Attendees

Markus
Yvonne
Daniel
Adi
Moritz
Christoph N.
Chris K.
Jannis
Felix

Buddies

Moritz & Chris K.
Jannis & Christoph N.
Adi & Daniel

Agenda

09:00 welcome, high-five
Felix nearly done
Protocol: Jannis
buddy talk: case study
PermaplanT 1.0
- no tablet support but multi-browser
- no offline support but collaboration
- no range selection but timeline
- no alternatives but creation of layers
- reduce to essential layers
PermaplanT 0.3.5
- fix planting of seeds (mark with envelope in common search)
- usability improvements (multi-select, sizes of plants)
sprint plan
estimation of use case complexity
outlook

Tasks for Everyone

To be done until Friday 20.10.2023:

submit a (short) text in submissions
buddy talk
Get current issues, PRs and use cases (UC) done
Create/update issues/tests (behavior driven) as needed for future tasks
Update sprint plan
Do reviews of PRs in main repo and submissions

Individual Tasks

To be done until Friday 20.10.2023:

Felix: Modul Dokumentation, Schnittstellenbeschreibung mit Fehler, Shutdown&Watchdog Beschreibung/Drop, fix issues
Jannis: finish NC chat+online status, milestone plan, Dockerfile neues Rust, 2 first PermaplanT issues
Moritz: seeds search, seed UC done, issue seeds on the map, (base layer auto?)
Daniel: keybinding+timeline decisions/concept, impl notes?
Christoph: UC merge, usability guidelines, (PR seed search), ctrl+shift als issue, issues
Adi: nur E2E: seeds tests, exceptions, concurrency
Chris: scraper fertig, plants hierarchy+relations

Meeting Notes

Layer state management is the most complex aspect of the PermaPlanT frontend right now due to the collaboration feature.

Copy&Paste collaboration feature is too complex as just another use case => needs to be split up.

Number of layers restricted by library konva, they recommend only a few (4-5) layers. This is a problem before we add more layers. Konva does offer groups with simillar API to layers. Issue #952

Judge complexity in fibonachi number story points. Story points are not mapp

Meeting 2023-10-23

Attendees

Markus
Yvonne
Adi
Moritz
Christoph N.
Daniel (Protocol done)
Jannis (Protocol done)

Not here:

Chris K.

Buddies

Moritz & Chris K.
Jannis & Christoph N.
Adi & Daniel

Agenda

09:00 permaculture principles
Protocol: Daniel
Felix finished!
praise:
- great questions by everyone
- excellent reviews by Christoph
empty plant menus:
- Do we wanna inform the user when he has no seeds, as we do now (in prod)?
- Do we wanna offer him the possibility, via some action link, to go directly to the seeds page to create some, as we do now (in prod)?
improving communication: issues describing what you want to do
event handling:
- Where to bind keylisteners (especially for konva layers)?
framework scope
focus -> standard
forms?
- Should we type available keys and actions (enums?, constants?)?
- Do we want to use https://www.npmjs.com/package/react-hotkeys-hook? -> rather not, concept first
reihenfolge: #1000 merge?
nicht zu sehr auf esc
PermaplanT 0.3.5
- fix planting of seeds
- usability improvements (multi-select, sizes of plants)
sprint plan
outlook

Tasks for Everyone

To be done until Friday 27.10.2023:

submit a (short) text in submissions
buddy talk
Get current issues, PRs and use cases (UC) done
Create/update issues/tests (behavior driven) as needed for future tasks
Update sprint plan
Do reviews of PRs in main repo and submissions

Individual Tasks

To be done until Friday 27.10.2023:

Felix: fertig
Jannis: finish NC chat, milestone plan, Dockerfile neues Rust, 2 first PermaplanT issues
Moritz: layers vs. groups, issue seeds on the map, base layer auto, (snap tests)
Christoph: usability guidelines, multi-select UC, issues von user studie erstellen
Daniel: keybinding+timeline decisions/concept, notes+prototyping, refactoring
Adi: PRs abschließen, E2E merge: seeds tests, exceptions, concurrency
Chris: scraper fertig, plants hierarchy+relations

Meeting Notes

permaculture principles examples: - Yvonne: composting can be accelerated by higher temperature; efficient distances - Markus: speak about details to define clear issues; use time and personal energy efficiently - Adi: automation (pipelines, tests) - Christoph: push every day - Moritz: keep on working every day

event handling discussion - we use one single json (source of truth) for keybindings (Actions as key and shortcuts as value) - in keyhandlers for konva it has to be checked if corresponding layer is active - html element should be passed to hook - Daniel will update decision

layers vs groups - nothing done yet

design guidlines

if rules are broken a comment should be added that explains de decision

Meeting 2023-10-30

Attendees

Markus
Yvonne
Moritz
Samuel
Christoph N. (3x Protocol done)
Daniel (Protocol done)
Jannis (Protocol done)

Not here:

Adi
Chris K.

Buddies

Moritz & Chris K. & Samuel
Jannis & Christoph N.
Adi & Daniel

Agenda

09:00 welcome, introduce each other
Protocol: Christoph N.
PermaplanT 0.3.5
- fix planting of seeds
- usability improvements (multi-select, sizes of plants)
Conclusions/current state of:
- UI guidelines
- listeners
- key bindings
- layers vs. groups -> change to groups
sprint plan
outlook

Tasks for Everyone

To be done until Friday 3.11.2023:

PRs review and merge
review of guidelines
buddy talk about guidelines
get current issues, PRs and use cases (UC) done
create/update issues/tests (behavior driven) as needed for future tasks
update sprint plan
do reviews of PRs in main repo and submissions
Submit a (short) text in submissions

Individual Tasks

To be done until Friday 3.11.2023:

Moritz: issue seeds on the map, naming, groups PR, base layer auto, snap tests
Christoph: multi-select extensions (ctrl/shift), area of plants, issues von user studie erstellen
Jannis: finish NC chat, milestone plan, Dockerfile neues Rust, mehrjährige pflanzen, remove variety
Daniel: keybinding+timeline decisions/concept, notes+prototyping, refactoring
Samuel: review UI guidelines&PRs, landing page for mobile

Not here:

Chris: scraper fertig, plants hierarchy+relations
Adi: PRs abschließen, E2E merge: seeds tests, exceptions, concurrency

Meeting Notes

TODOs for upcoming release

Fix plant naming
Various usability improvements

Misc

UI/Usability guideline:
- reviews
- guidelines not set in stone
- need to be constantly adapted and enhanced
Keybindings:
- try to reduce to 2 layers max: top level (global, layers, etc.) and second level (actions)
- developer info section (top level) for shortcuts which should never be customized
Layers vs Groups:
- performance-wise no difference at page load (a few milliseconds)
- tested with a few thousands nodes
- tendentially better performance with groups (~50ms)
- functionality still working
- future plan: test with many more layers
- conclusion: (more than likely) go with groups

Meeting 2023-11-06

Attendees

Markus
Yvonne
Moritz
Daniel (Protocol done)
Adi

Not here:

Samuel
Jannis (Protocol done)

Buddies

Moritz & Samuel
Jannis & Christoph N.
Adi & Daniel

Agenda

09:00 welcome, mood
Christoph N. nearly finished
buddy talk
Protocol: Moritz
PermaplanT 0.3.5
- fix planting of seeds
- usability improvements and multi-select
Conclusions/current state of:
- UI guidelines (reviews missing)
- key bindings
- layers vs. groups -> change to groups
PRs review and merge
sprint plan
outlook

Tasks for Everyone

To be done until Friday 10.11.2023:

vote for https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/27
review of guidelines
get current issues, PRs and use cases (UC) done
create/update issues/tests (behavior driven) as needed for future tasks
do/update sprint plan
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 10.11.2023:

Daniel: keybinding decisions/concept+refactoring, refactoring, plant notes, prepare timeline for feedback
Moritz: finish PRs snap tests #1038, base layer finish (scaling, polygon)
Adi: master fix, timeline fix, Release Prep, E2E merge: seeds test

Not here:

Jannis: finish NC chat, milestone plan, Dockerfile neues Rust, mehrjährige pflanzen, remove variety
Samuel: reviews, landing page for mobile
Chris: scraper fertig, plants hierarchy+relations

Meeting Notes

Regarding the next release:

The following PRs should be included:

421 Keybinding refactoring.

Markdown editor in seeds page.

Base Layer auto scaling

Usability guideline; it has to be reviewed by all team members before merging.

The following major PRs/issues have been completed:

Seeds can now be planted on the map.

Usability improvements by Christoph

There are still a few open PRs assigned to Christoph.

These should be fixed by the remaining team.

Layers or the map planning system should be refactored to be more testable.

Meeting 2023-11-13

Attendees

Markus
Yvonne
Moritz (Protocol done)
Daniel (Protocol done)
Adi
Samuel

Not here:

Jannis (Protocol done)

Buddies

Moritz & Samuel
Adi & Daniel & Jannis

Agenda

09:00 welcome, mood
Christoph N. finished
buddy talk
Protocol: Adi
questions:
- did scaling change?
timeline:
- presentation
- feedback
workflow for reviews
PermaplanT 0.3.5 released!
- please rebase PRs
weekly tasks:
- always review meeting notes afterwards
- https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/27
Conclusions/current state of:
- UI guidelines (reviews missing)
- key bindings
- layers vs. groups -> change to groups
PRs review and merge
sprint plan
outlook

Tasks for Everyone

To be done until Friday 17.11.2023:

vote for https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/27
buddy topic: guidelines
review of meeting PR
get current issues, PRs and use cases (UC) done
create/update issues/tests (behavior driven) as needed for future tasks
do/update sprint plan
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 17.11.2023:

Daniel: refactoring merge, plant notes (guideline), timeline, warning, issues update
Moritz: finish PRs snap tests #1038, base layer finish (scaling, polygon)
Adi: E2E merge: seeds test, flaky test, Release Prep
Samuel: reviews, landing page for mobile

Not here:

Jannis: finish NC chat, milestone plan, Dockerfile neues Rust, mehrjährige pflanzen, remove variety
Chris: scraper fertig, plants hierarchy+relations

Meeting Notes

Timeline

problem with notes in multiselect, needs visual representation&warning if data differs
add two more icon state for debouncing indicator:
1. yellow triangle as warning if changes might have unwanted effects
2. red cross if query failed
jumping from 30/31th to february and then back, what happens? should pick last day
set back to normal opacity so charts can be seen better
maybe collapsable timeline? -> generally liked, but is a new feature
maybe have a select box to disable the diagrams -> rather not

Tasks done

Adi:
- 0.3.5 released
- E2E disabled on master
Daniel:
- Keybindings: different modifiers (alt, shift, ctrl)
Moritz:
- repeated error toasts
- plants connected with seeds

To do

(Also see above in "Individual Tasks" and issue tracker)

Daniel:
- finish timeline first usecase
- backend issue for timeline
- write guideline on how to properly do the multiselect
- layer warning (bad neighbours)
Moritz:
- conva max layers
- snaptests polygon
- additional name (bug) when planting from inventory
Adi:
- Finish seed tests
- Close open PR's
- Eventually release at the end of the week
Samuel:
- Reviews
- Fix slider bug
- Grabbing cursor

Meeting 2023-11-20

Attendees

Markus
Yvonne
Moritz (Protocol done)
Adi (Protocol done)
Jannis (Protocol done)
Samuel

Not here:

Daniel (Protocol done)

Buddies

Moritz & Samuel
Adi & Daniel & Jannis

Agenda

09:00 welcome, mood
buddy talk
Protocol: Samuel
Reinsaat.at, Paul
0.3.6 release today?
terminology for UI:
- left, right top/down toolbar (context)
- toasts
- status panel
- no title attributes? #1061
- Navigation Bar
tailwind CSS linter
write good code comments:
- small functions
- functions with design by contract
- assertions
- nicely written comments
- rationale (Konva)
weekly tasks:
- always review meeting notes afterwards
- https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/27
sprint plan
outlook

Tasks for Everyone

To be done until Friday 24.11.2023:

vote for https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/27
buddy topic: code improvements, comments
do/update sprint plan
tailwind CSS linter (frontend) #1073

If possible/needed, do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
review of meeting PR https://github.com/ElektraInitiative/PermaplanT/pull/1072/files
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 24.11.2023:

Jannis: push draft NC chat, PermaplanT: de+en plant names, (mehrjährige pflanzen, remove variety)
Samuel: reviews, help others, ranking/language/tooltips
Moritz: polygon, snap tests with Samuel
Adi: flaky tests, release

Not here:

Daniel: prepare for merges (timeline etc.), issues updates
Chris: scraper fertig, plants hierarchy+relations

Meeting Notes

release talk

Adi review of moritz PR for release merge tests and then 'Fix full plant name not shown. #1063'

Naming

Status Panel - Timeline

Linting have a look at tailwindcss eslint plugin and tailwindcss intellisense for VSCode

Code Comments

Sometimes useful to add rationales and link issues of external repos if that is the reason for a workaround.

Weekly tasks

Try to do all of the weekly tasks each week! Always look in meeting protocol what the tasks are.

What happened this week

Samuel: full page navbar for mobile, plant icon at cursor while planting (almost done), slider bugfix. Moritz: refactored/reworked base layer form Adi: some E2E seed tests implemented some are left for upcoming week

Meeting 2023-11-27

Attendees

Markus
Yvonne
Jannis
Daniel
Adi
Moritz
Samuel

Buddies

Moritz & Samuel
Adi & Daniel & Jannis

Agenda

09:00 welcome, mood
Protocol: Jannis
Paul
0.3.7 release
buddy talk code comments
tailwind CSS linter
weekly tasks:
- always review meeting notes afterwards
sprint plan
outlook

Tasks for Everyone

To be done until Friday 1.12.2023:

buddy talk topic: How are you?
do/update sprint plan
approve meeting notes, check for requested reviews https://github.com/ElektraInitiative/PermaplanT/pulls?q=is%3Apr+is%3Aopen+user-review-requested%3A%40me

If possible/needed, do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
review of meeting PR https://github.com/ElektraInitiative/PermaplanT/pull/1072/files
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 1.12.2023:

Daniel: timeline mergen, UC issues weiter
Jannis: push draft NC chat, PermaplanT: de+en plant names, (mehrjährige pflanzen, remove variety)
Samuel: reviews, help others, ranking/language/tooltips, docu tests
Moritz: polygon, snap tests with Samuel, broadcasting issue für Paul, (group instead of layers)
Adi: e2e with Samuel

Not here:

Chris: scraper fertig, plants hierarchy+relations

Meeting Notes

Plants with is_tree should get a different icon (wavy lines).
CSS tailwind parser needs more time for conclusion.
changing to new test framework, Samuel should document outcome.
Zoom in map editor should be different maybe faster steps per zoom as easiest solution.

Meeting 2023-12-04

Attendees

Markus
Yvonne
Daniel
Moritz
Samuel

Not here:

Jannis (Protocol done)

Buddies

Moritz & Samuel
Daniel & Jannis

Agenda

09:00 welcome, associations
Protocol: Daniel
buddy talk "How are you"
tailwind CSS linter v2
! we update to rust 1.74, do rustup update
more consolidated REST APIs
weekly tasks:
- always review meeting notes afterwards
sprint plan
outlook

Tasks for Everyone

To be done until Friday 8.12.2023:

buddy talk topic: reviews+get PRs merged
do/update sprint plan
approve meeting notes, check for requested reviews https://github.com/ElektraInitiative/PermaplanT/pulls?q=is%3Apr+is%3Aopen+user-review-requested%3A%40me

If possible/needed, do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
review of meeting PR https://github.com/ElektraInitiative/PermaplanT/pull/1072/files
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 8.12.2023:

Daniel: timeline mergen, REST APIs def, UC issues weiter, review polygon
Samuel: reviews, help others, ranking/language/tooltips, documentation of unit tests
Moritz: polygon, snap tests with Samuel, group instead of layers
Jannis: push draft NC chat, PermaplanT: de+en plant names, (mehrjährige pflanzen, remove variety)

Meeting Notes

warnings layer: backend implementation will be done first, warnings are generated in backend. Issue for backend is to be created.
labels should always be shown in forms
planting: it would be nice if planted plant could be resized before next plant is planted in planting mode. If this is not possible, selection is not necessary at all.
polygons: feature looks great, should be reused for drawing layer
tailwind linter won't be added to CI for now. However, frontend devs should install it locally.
Rust version has to be updated locally
There seems to be a problem with our react hooks so that calls are done too often. We will investigate this if performace issues occur. New code should already be written with more care.

Meeting 2023-12-11

Attendees

Markus
Yvonne
Moritz
Daniel (Protocol done)

Not here:

Samuel
Jannis (Protocol done)

Buddies

Daniel & Moritz
Moritz & Samuel
Daniel & Jannis

Agenda

09:00 welcome, advices
(no protocol necessary)
buddy talk "reviews+get PRs merged"
Adi will continue doing releases
new redirects git.permaplant.net issues.permaplant.net pulls.permaplant.net pull.permaplant.net project.permaplant.net tree.permaplant.net blob.permaplant.net milestone.permaplant.net (see below how to use them)
methodology in benchmarks (median, statistics, improvements)
tailwind CSS linter v3
always review meeting notes afterwards
sprint plan

Tasks for Everyone

To be done until Friday 15.12.2023:

buddy talk topic: methodology (Daniel & Moritz)
do/update sprint plan
approve meeting PR #1116, check for requested reviews

If possible/needed, do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 15.12.2023:

Daniel: timeline mergen, UC issues! weiter drawing layer
Moritz: group instead of layers, heat map, (snap tests with Samuel)

One week break:

Jannis: push draft NC chat, PermaplanT: de+en plant names, (mehrjährige pflanzen, remove variety)
Samuel: reviews, help others, ranking/language/tooltips, documentation of unit tests

Meeting Notes

Meeting 2023-12-18

Attendees

Markus
Yvonne
Moritz
Daniel (Protocol done)
Samuel
Christoph

Break:

Jannis (Protocol done)

Buddies

Moritz & Samuel
Daniel & Christoph

Agenda

09:00 welcome, advices
Protocol: Christoph
Next two weeks:
- (26ter 15:00 Chris)
- 27th December 9:00 Chris, Daniel, Moritz?
- 2nd January 9:00 Chris, Daniel
migrate to vitest, done in #1120, #1038 closed
test strategy to be udpated
sprint plan

Tasks for Everyone

To be done until Friday 22.12.2023:

buddy talk topic: any topic as needed
do/update sprint plan
approve meeting PR #1129, check for requested reviews

If possible/needed, do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 22.12.2023:

Samuel: reviews, help others, documentation of unit tests
Daniel: timeline next PR, continue drawing layer frontend
Moritz: create shade layer UC issues, group instead of layers, heat map, write about performance tests
Christoph: finish scraper, plants hierarchy+relations

Break:

Jannis: push draft NC chat, PermaplanT: de+en plant names

Meeting Notes

new teammember Daniel - Christoph is back!
please review #1087
change in test strategy, no testing of whole pages as too much effort for too little outcome

Meeting 2023-12-27

Attendees

Markus
Yvonne
Daniel (Protocol done)

Break:

Samuel
Jannis (Protocol done)
Christoph (Protocol done)
Moritz

Buddies

Moritz & Samuel
Daniel & Christoph & Jannis

Agenda

09:00 welcome
Protocol: Daniel
Next meeting 2nd January 9:00 Chris, Daniel
sprint plan

Tasks for Everyone

To be done until Sunday 31.12.2023:

buddy talk topic: improvement of documentation
do/update sprint plan
approve meeting PR #1129, check for requested reviews

If possible/needed, do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Sunday 31.12.2023:

Daniel: PRs finish, continue drawing layer frontend, create drawing layer backend issue, check events performance, create layers and label layer issues

Break:

Christoph: finish docu&scraper, plants hierarchy+relations
Moritz (?): create shade layer UC issues, group instead of layers, heat map, write about performance tests
Samuel: reviews, help others, documentation of unit tests
Jannis: push draft NC chat, PermaplanT: de+en plant names

Meeting notes

Polygons can be closed by clicking on start point
bezier anchors should always be shown when in editing mode of polygon
lines should be stored relative to starting point so that moving of elements can be done equally for each element
all error toasts should be automatically closed

Meeting 2024-01-02

Attendees

Markus
Yvonne
Daniel (Protocol done)

Break:

Samuel
Jannis (Protocol done)
Christoph (Protocol done)
Moritz

Buddies

Moritz & Samuel
Daniel & Christoph & Jannis

Agenda

09:00 welcome
Protocol: Daniel
sprint plan

Tasks for Everyone

To be done until Friday 05.01.2024:

buddy talk topic: improvement of documentation
do/update sprint plan
approve meeting PR #1129, check for requested reviews

If possible/needed, do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 05.01.2024:

Daniel: PRs finish, continue drawing layer frontend, create drawing layer backend issue, check events performance, create layers and label layer issues

Break:

Christoph: finish docu&scraper, plants hierarchy+relations
Moritz (?): create shade layer UC issues, group instead of layers, heat map, write about performance tests
Samuel: reviews, help others, documentation of unit tests
Jannis: push draft NC chat, PermaplanT: de+en plant names

Meeting notes

new layer: - modal with name and type (only drawing and labels) - new layer will be placed after enabled one - new layer is visible with 100% opacity
drawing: - arrows should be available

Meeting 2024-01-08

Attendees

Markus
Yvonne
Daniel (Protocol done)
Jannis (Protocol done)
Christoph
Moritz

Nicht da:

Samuel

Buddies

Moritz & Samuel
Daniel & Jannis & Christoph

Agenda

09:00 3 questions for year 2024
welcome: Christoph
Protocol: Christoph
Diagrams in Bachelor Thesis
sprint plan

Tasks for Everyone

To be done until Friday 12.01.2024:

buddy talk topic: improvement of documentation
do/update sprint plan
approve meeting PR #1129, check for requested reviews

If possible/needed do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 12.01.2024:

Daniel: drawing layer backend, create layers and label layer issues
Moritz: create shade layer UC issues (8-edges, size selectable, overlap), (group instead of layers)
Jannis: review heatmap, notes+drawing layer
Christoph: architektur, review heatmap+db docu
Samuel: reviews, help others, documentation of unit tests

Meeting notes

Drawing Layer: Double click to finish bezier/polygon
Überlegungen über Refactoring der gemeinsamen Fähigkeiten der Layer
Koordination mit Backend: Evtl. alles als Geometry/Polygon speichern, jedenfalls keine neuen Textrepräsentationen erfinden
Moritz: Shading Layer, Diskussion über Brush vs. Polygon
Jannis, Christoph: Heatmap PR reviewen

Meeting 2024-01-15

Attendees

Markus
Yvonne
Daniel (Protocol done)
Jannis (Protocol done)
Christoph (Protocol done)
Moritz

Buddies

Moritz & Christoph
Daniel & Jannis

Agenda

09:00 Kennenlernen+Checkin
Protocol: Moritz
shadings tests
release
Samuel
please do "Tasks for Everyone" and individual tasks
- get PRs and UCs done
- please meet deadlines, so that reviews etc. can be done
API documentation
median
sprint plan

Tasks for Everyone

To be done until Friday 19.01.2024:

buddy talk topic: improvement of (API) documentation
do/update sprint plan
approve meeting PR #1157, check for requested reviews

If possible/needed do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 19.01.2024:

Daniel: endpoint requirements, notes
Jannis:notes, API refactoring, doc/decisions/backend_orm_crate.md, (timeline)
Christoph: landingpage, spread&height, review heatmap+db docu
Moritz: group instead of layers, create shade layer UC issues (8-edges, size selectable, overlap)
Yvonne: Shading Testen
Markus: Release

Meeting Notes

Raw SQL queries should be preferred over typed queries for increased developer ergonomics. The next release should focus on minor bug fixes and frontpage updates. Samuel will no longer be able to work for PermaplanT due to personal reasons.

Plants should not be mapped into three size categories, but use a simple size field instead.

Every team member is reminded to keep up with their weekly tasks, especially with reviewing the weekly meeting notes PR. Tasks should be done as soon as possible after the weekly meeting on monday.

Backend tasks should be done primarily by our dedicated Backend-Devs. Frontend teammembers should submit requests for required APIs as prose text. Swagger APIs docs need to be reworked for a large portion of APIs.

Meeting 2024-01-22

Attendees

Markus
Yvonne
Daniel
Jannis
Christoph
Moritz

Buddies

Moritz & Christoph
Daniel & Jannis

Agenda

09:00 start
Protocol: Daniel
Permakultur Prinzipien
buddy talk topic
- last week: improvement of (API) documentation
- this week: Permakultur Prinzipien
shadings tests
- plants should be on top of heatmap
- make shades snap to grid/pixels -> eher nicht
- yellow/red colors (Christoph)
- permanent deep shade probably not need (will be clarified by Yvonne)
- legend inconsistent to backend/src/model/entity.rs
simplify non-semantic layers
- landscape, fertilize is only a renamed drawing layer with different icons
release preparation ongoing (testing)
bad availability from Wednesday
architecture:
- docu and code should always fit together! enum descriptions etc.
- security guidelines
- modification, creation (all elements)
thx for doing "Tasks for Everyone"
- clarify as much as possible in advance using issues
- split issues frontend/backend
- reviews check requirements and check what is tested
sprint plan

Tasks for Everyone

To be done until Friday 26.01.2024:

buddy talk topic: Permakultur Prinzipien
do/update sprint plan
approve meeting PR #1157, check for requested reviews

If possible/needed do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 26.01.2024:

Daniel: notes
Jannis: timeline, 2 small issues,
Christoph: landingpage, spread&height, db docu, heatmap
Moritz: finish shade layer PR
Yvonne: Testen, check Shading
Markus:

Meeting Notes

Principles:

"Get a yield": extract positives for oneself
"Design form patterns to details": start in general and focus on details later
Daniel: Minimal Viable Product: product with enough features to attract early-adopter customers and validate a product idea early in the product development cycle
Christoph: told example that he focused on font size in ER diagrams to much and lost focus on the whole.
Jannis: found solution to implement transactions in Diesel -> a great yield

Technical Part:

Jannis finished planting note PR
we should try to create small PRs
Markus creates security guidelines that have to be reviewed after completion.
In reviews, we should write down what we focused on.

Meeting 2024-01-29

Attendees

Markus
Yvonne
Jannis
Christoph
Moritz

Ill:

Daniel (Protocol done)

Buddies

Moritz & Christoph
Daniel & Jannis

Agenda

09:00 start
(Yvonne) Permakultur Prinzipien
Protocol: Jannis
focus groups
- e2e (with Adi, maybe Moritz in the beginning)
- gis (with Karsten)
buddy talk topic
- last week: Permakultur Prinzipien
- next week: SQL decision
shadings issues to be created:
- plants should be on top of heatmap
- yellow/red colors (Christoph)
- PermanenT deep shade probably not need
- legend inconsistent to backend/src/model/entity.rs
- correct positioning of heatmap
sprint plan
80/20 rule for thesis
raw SQL decision:
- formatting -> sqlfluff?
- testing of SQL?
- squash migrations before releases?
improvement of (API) documentation
architecture:
- security guidelines
- modification, creation (all elements)
(again) bad availability on Wednesday

Tasks for Everyone

To be done until Friday 2.2.2024:

vote for meeting https://nextcloud.markus-raab.org/nextcloud/index.php/apps/polls/vote/29
buddy talk topic: SQL decision
do/update sprint plan
approve meeting PR #1157, check for requested reviews

If possible/needed do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 2.2.2024:

Daniel: notes
Jannis: timeline, drawing layer, tutorial for layer creation (creation/update metadata + what interface should any layer have)
Christoph: db docu, heatmap, meeting
Moritz: finish shade layer PR, grid, (label sizes)
Yvonne: Testen, check Shading
Markus:

Meeting Notes

Karsten - new potential PermaplanT developer who is an expert in PostGIS.
Topic specific focus group meetings with select members (selected by topic).
Buddy talks are meant to encourage engagement in the group. The weekly meeting shouldn't be the only contact between PermaplanT members.
Guideline to prefer batch operations (like in plantings) for Atomic map operations e.g for drawings. We need guidelines for what a new layer API should always include: (cration/update metadata, needed CRUD endpoints).
Frontend renders some components (like timeline) very slowly (unnecessary work by component), in the case of the timeline this will be fixed, other issues need further investigations.
breaks should be 13-15minutes

Meeting 2024-02-05

Attendees

Markus
Yvonne
Daniel (Protocol done, cannot come 12.2)
Jannis (Protocol done)
Christoph

Not here:

Moritz

Buddies

Moritz & Christoph
Daniel & Jannis: timeline
Jannis & Christoph: review backend, who will focus on what?

Agenda

09:00 start
Protocol: Christoph
report from focus group GIS (with Karsten)
going forward with brushes
buddy talk topic
- last week: SQL decision
- next week: choose your own
focus group today 17:00 e2e (with Adi, maybe Moritz in the beginning)
shadings issues to be created:
- coding quality
- plants should be on top of heatmap
- yellow/red colors (Christoph)
- PermanenT deep shade probably not need
- legend inconsistent to backend/src/model/entity.rs
- correct positioning of heatmap
experimental setups
DB documentation
cleanup branches
- 1168-test
raw SQL decision:
- formatting -> sqlfluff?
- testing of SQL?
- squash migrations before releases?
layers vs. groups performance
sprint plan

Tasks for Everyone

To be done until Friday 9.2.2024:

buddy talk topic: see above
do/update sprint plan
approve meeting PR #1157, check for requested reviews

If possible/needed do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 9.2.2024:

Jannis: finish timeline, (drawing layer), tutorial for layer creation (creation/update metadata + what interface should any layer have)
Daniel: notes, finish timeline, polygon libraries/algorithms
Christoph: scraper, db docu (+issue db comments), heatmap benchmark+color scale, meeting
Moritz: finish shade layer PR, grid, (label sizes)
Yvonne: heatmap concept
Markus:

Meeting Notes

Report from focus group GISCall with Karsten, a highly-experienced GIS expert. Suggested raster files but had concerns in the same time. General GIS approach: Open layers or similar for frontend, map server for backend. Karsten is willing to answer further questions concerning GIS and PostGIS.

Brushes: Vorab auswählen welcher Brush verwendet wird. Überlappende Polygone vom gleichen Typ sollen sich vereinen. Zeichnet man mit einem Brush von einem anderen Typ, überzeichnet man alte Polygone. Ein bestehendes Polygon muss selektiert werden um es erweitern zu können. Ob und in welcher Auflösung gezeichnete Polygone geglättet werden, hängt von den verwendeten Libraries/Funktionen ab (Entscheidung aufgeschoben). Performantester Algorithmus soll genommen werden. Aktueller Ansatz: Wir bleiben dabei Polygone ans Backend zu schicken. Zwei zusätzliche Endpoints: Polygone addieren (union); Polygone subtrahieren (set difference)

Daniel und Jannis reden im Buddy Talk über die Timeline Jannis und Christoph reden im Buddy Talk über Aufgabenverteilung/Fokus im Backend

Christoph: Überprüfe Performance der Heatmap mit ~10.000 gut platzierten Shadings

Mit anderen Communities im Kontakt bleiben: Fragen stellen / Probleme melden (konva.js; diesel)

Meeting 2024-02-12

Attendees

Markus
Yvonne
Christoph

Not here:

Moritz
Daniel
Jannis

Buddies

Moritz & Christoph
Daniel & Jannis: timeline
Jannis & Christoph: review backend, who will focus on what?

Agenda

09:00 start
Protocol: Christoph
buddy talk
feedback
new pictures Yvonne
integer for plant spread
move away from utopia
minimal env vars for backend
DB documentation
sprint plan

Open Points

what to write in release notes (migrations, new scraper data)
layers vs. groups performance
raw SQL decision:
- formatting -> sqlfluff?
- testing of SQL?
- squash migrations before releases?
cleanup branches
- 1168-test
shadings issues to be created:
- coding quality
- plants should be on top of heatmap
- yellow/red colors (Christoph)
- PermanenT deep shade probably not need
- legend inconsistent to backend/src/model/entity.rs
- correct positioning of heatmap
- heatmap shown as layer?

Tasks for Everyone

To be done until Friday 16.2.2024:

buddy talk topic: see above
do/update sprint plan
approve meeting PR #1187, check for requested reviews

If possible/needed do:

create/update issues/tests (behavior driven) as needed for future tasks
get current issues, PRs and use cases (UC) done
do reviews of PRs in main repo and submissions
submit a (short) text in submissions

Individual Tasks

To be done until Friday 16.2.2024:

Jannis: finish timeline, (drawing layer), tutorial for layer creation (creation/update metadata + what interface should any layer have)
Christoph: scraper overrides+German names, heatmap benchmark, how to add entry
Yvonne: heatmap concept
Markus:

not here:

Daniel: notes, finish timeline, polygon libraries/algorithms
Moritz: finish shade layer PR, grid, (label sizes)

Meeting Notes

DB Docu: Zumindest eine Entity ausprobieren; Migration etc. erstellen; eventuell alles in eine Migration Tutorial um eine Spalte hinzuzufügen (welche Stellen müssen angepasst werden) Guidelines für DB Documentation

Update validation guidelines: Wo sollen welche Checks / Validations durchgeführt werden (Rust vs Database Constraints)

Meeting 2024-02-19

Next Meeting 11.3.2024

Attendees

Markus
Christoph (protocol done)
Daniel
Jannis
Moritz

Holiday:

Yvonne

Buddies

Daniel & Jannis: timeline
Jannis & Christoph: review backend, who will focus on what?
Daniel & Christoph: evtl. e2e tests

Agenda

09:00 start
buddy talks
Tip
Protocol: Daniel
Polygons
change in env vars for backend
decisions:
- Daniel: konva support lib, best hull algorithm
- Jannis: move away from utopia
- Christoph+Jannis: DB documentation, verlinkung
- Jannis: raw SQL
get PRs closed
first steps in written thesis/TISS
meeting every 3 weeks
sprint plan
next time: efficient way to not forget anything in sprint

Tasks for Everyone

To be done until Friday 23.2.2024:

buddy talk
approve meeting PR #1190
create decision PRs to start discussion
submit a (short) text in submissions

To be done until Friday 1.3.2024:

buddy talk
check for requested reviews
review 2x (short) text in submissions

To be done until Friday 8.3.2024:

buddy talk
fix reviews and re-request review
benchmarks
all PRs from before 20.2.2023 are merged
create new issues for next spring
do/update sprint plan

Individual Tasks

To be done until Friday 8.3.2024 (step by step, start early!):

Daniel: notes, finish timeline, drawing layer first version, polygon libraries/algorithms benchmarks, RQ, keybinding konzept
Jannis: TISS Text, merge open prs, drawing layer, tutorial for layer creation (creation/update metadata + what interface should any layer have), DB Doku
Christoph: TISS Text, scraper overrides+German names, Gabriel, SQL heatmap benchmark, how to add column in tables

Meeting Notes

Daniel should look for libraries for polygon operations
- hull.js currently seems to be the best solution for calculation hull
we have to check performance if many free lines are drawn
we have to define our research questions
we have to write missing TISS texts

Meeting 2024-03-11

next meeting 25.3.2024

Attendees

Markus
Daniel (protocol done)
Jannis
Yvonne
Moritz

Excused:

Christoph (protocol done)

Buddies

Jannis & Christoph: review backend, who will focus on what?
Daniel & Christoph & Moritz: fix/add e2e tests

Agenda

09:00 start
welcome: "Mein Erfolg"
Protocol: Jannis
buddy talks
new members
rework notification system (Jannis)
decisions:
- Daniel: konva support lib, best hull algorithm
- Jannis: move away from utopia
- Christoph+Jannis: DB documentation, verlinkung
- Jannis: raw SQL
English
- its
- Initiative
- FLOSS
general tasks:
- more reviews needed
- get PRs closed
- add more (manual) e2e tests
~~efficient way to not forget anything in sprint~~ (not discussed, as we will improve sprint planning)
first steps in written thesis/TISS
sprint plan
10:30 end

Tasks for Everyone

To be done until Friday 15.3.2024:

buddy talk
approve meeting PR #1204
create decision PRs to start discussion
check for requested reviews

To be done until Friday 22.3.2024:

buddy talk
create new issues for next sprint
review at least 1 PRs per created PR
do/update sprint plan

Individual Tasks

To be done until Friday 22.3.2024 (step by step, start early!):

Daniel: notes, finish timeline, drawing layer first version, polygon libraries/algorithms benchmarks, RQ, keybinding konzept
Jannis: TISS Text, merge open prs, drawing layer, tutorial for layer creation (creation/update metadata + what interface should any layer have), DB Doku, notification profilen
Moritz: group vs. layer durchdenken und PR (5 layer, mit ein paar gruppen), alte branches durchschauen

Excused:

Christoph: TISS Text, scraper overrides+German names, Gabriel, SQL heatmap benchmark, how to add column in tables

Meeting Notes

Notification system to be expanded/improved
All clients get all messages at the moment, not yet filtered
Message performance+authentication+filtering topic for Jannis
Moritz: React state management is tricky, we have frequent rendering bugs. Now: Apart from memory our performance is ok.
Often network problems during building, you need to trigger CI manually in PRs.

Meeting 25.03.2024

next meeting 2.4.2024 9:00 (without Jannis)

Attendees

Markus
Daniel (protocol done)
Jannis (protocol done)
Christoph (protocol done)
Moritz
Andrei
Lukas
Yvonne

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
new members
welcome
buddy talks: first contact
protocol: Moritz
create issues: Andrei
new issues use cases
- heatmap as normal layer (Moritz)
- heatmap and relation layer has same content (Daniel&Andrei)
  - (bi)annual plants
- additional layer concept (Daniel)
- read-only non-member (Andrei)
  - no plant data should leak to non-member
GitHub vs. GitLab
decisions:
- rework notification system (Jannis+Andrei)
- Jannis: move away from utopia
- Christoph+Jannis: DB documentation, verlinkung
- Jannis: raw SQL
TISS texts review
Scrum:
- reviews
- PRs closed
- (manual) e2e tests
better diffs: https://difftastic.wilfred.me.uk/
sprint plan

Tasks for Everyone

To be done until Friday 29.03.2024:

buddy talk: first contact, dev setup
approve meeting PR #1220
create decision PRs to start discussion
2x review requested reviews
do/update sprint plan

Individual Tasks

To be done until Friday 29.03.2024:

Andrei: copy&paste issues, scrum
Daniel: finish timeline, drawing layer first version, finish keybinding
Jannis: creation times reviews missing, drawing layer, tutorial for layer creation (creation/update metadata + what interface should any layer have), review DB Doku from Christoph, notification profilen, TISS Text
Moritz: group vs. layer new PR
Christoph: TISS Text, scraper overrides+German names, Gabriel Thesis, SQL heatmap benchmark, how to add column in tables
Lukas: crop rotation design, review PRs, fix first issue (assigned)

Meeting Notes

Andrei will help to improve our workflows. He has experience in SCRUM-teams and relevant certifications.

A poll was held to decide whether the Project should migrate to Gitlab over Github. The results were inconclusive, most teammembers voted "both are fine". Next steps are on technical feasibility.

Heatmap should be exposed as a "normal layer" (2nd position after plant). Other Positions are to be decided.

An extra meeting is needed for the "relation-layer". It will show additional textual information related to plant relations, that is not covered by the heat map (Daniel & Andre will be assigned). An incomplete use case already exists.

The choice of important libraries, that are not easily replaced, should be justified in a decision document.

The words "model" and "entity" have been used to refer to the same concept. "Entity" should be added to glossary and from now on only "entity" should be used.

Meeting 02.04.2024

next meeting 8.4.2024 9:00

Attendees

Markus
Yvonne
Daniel (protocol done)
Christoph (protocol done)
Moritz (protocol done)
Lukas
Andrei (Scrum Master)
Filip

Could not come:

Jannis (protocol done)

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
welcome Filip (CI)
protocol: Lukas
GitLab Tuwien migration
upcoming next release (Filip+Adi)
content:
- drawing layer names (several ones): https://pull.permaplant.net/1236/files
scrum with Andrei:
- issues
- reviews -> later
- (manual) e2e tests -> later Christoph+Filip
last sprint before release
create issues:
- rework notification system (Jannis+Andrei)
- Jannis: raw SQL
TISS texts second round later
sprint plan

Tasks for Everyone

To be done until Friday 05.04.2024:

buddy talk: dev setup+docu
GitLab Tuwien migration: do a login via SSO on https://git.tuwien.ac.at
approve meeting PR #1233
request and approve for requested reviews requested reviews
do/update sprint plan

Individual Tasks

To be done until Friday 05.04.2024:

Filip: first issue: deploy docu, test migrations
Andrei: create issues, write about dates for scrum meeting
Daniel: finish timeline, meeting refactor layers
Jannis: creation times reviews missing, tutorial for layer creation (creation/update metadata + what interface should any layer have), review DB Doku from Christoph, notification profilen, TISS Text
Moritz: investigate how many layers?, group vs. layer new PR, meeting refactoring
Christoph: TISS Text, SQL heatmap benchmark, how to add column in tables, hierarchy, documentation decision update
Lukas: review PRs, fix first issue (assigned)
Yvonne: find manually inserted data in CSV

Meeting Notes

Filip maybe does not need to attend the meeting every week. This is to be decided on with him.

The repository will be migrated to the TU Wien Gitlab, which is unfortunately private, and later maybe to a self hosted instance which then also can be public.

The release should be done soon it is already overdue. Filip should be a part of it to get a first insight in the procedure.

Andrei will be starting creating issues from this meeting and from use cases.

The reviewing of PRs will be staying the same for another week before a new process is established. I.e. please review other PRs by yourself and invite buddies and others to review PRs.

To be able to add other layers backend migration needs to be done once the frontend supports it.

The bug that causes the timeline not to be selected in the centered element after resizing the y-axis on the map page is not release critical but would be nice-to have, also to complete the whole timeline use case.

The heatmap can not be merged to master yet because it is semantically incorrect but the refactoring can more easily be done after merging the heatmap into master.

Some PRs grew too big in the past which came from bad issue management and problems in communication (e.g. not talking about blockers!). Issues need to be broken down so small to be solvable in one week.

Investigation should be done by Moritz to find out what should stay as layer and what should become a group.

A separate meeting will be held to discuss:

crop rotation implementations and research (with Lukas), and
new development processes (with Andrei).

Meeting 04.04.2024 - Scrum Processes

Participants

Markus
Andrei
Yvonne

Questions

The main questions to answer:

How can we improve the way we create and work on issues?
How can we improve the way we deal with reviews of PRs?

Takeaways:

Every 3 weeks, include a 30min retro in the meeting by Andrei
After releases, we have small demo so team is up to date with what's new.
Explore how GitLab can help us structure issues around Use Cases/Features
Try to have only issues that have an estimation of one week (can be done in the scope of one "sprint") - If they are too big, they should be broken down into sub-tasks
Reviews should be more structured - what type of review is it? (what should be checked - code/documentation/testing etc.), what issue is it relating to
Submissions README.md as source of "expertise" - reviewers that match the expertise needed
Look into having separate "Master" and "Dev" Branches

Meeting Notes

General points brought up and short discussion on each:

Timeboxes from Scrum
- Don't fully make sense in the scope of the project, sprints can't be longer than 1 week if there are no other regular touchpoints (e.g Daily Scrum)
Retro/Review
- Might be interesting to try and integrate those concepts in our current meeting flow
From Use Cases to Issues to Pull Requests
- We need a better structure, like the concept of "Epic"s or "Feature"s to categorize the issues. This might be better supported by moving to GitLab
- What kind of info should an issue contain? From Use Cases to everything needed for implementation - currently, details might be missing that we only become aware of later
PRs and Reviews
- Important to have a clear linking between the PR and the task it relates to, clear indication of what the Scope of the PR is, try not to combine multiple issues into one PR
- Who should review? - we can use information from the submissions readme and have some rules of assigning reviews based on expertise - who can most help you review the part of the application you changed
- PRs should not stay open for too long, to keep the Branches more stable and avoid conflicts
- We should clean the older/"orphaned" PRs
Task Estimation
- In the past, explicit estimation did not work well for the structure of the project. Try to stick to Issue size that is managable in the "sprint" time of one week

Meeting 08.04.2024

Attendees

Markus
Yvonne
Daniel (protocol done)
Christoph (protocol done)
Moritz (protocol done)
Jannis (protocol done)
Lukas (protocol done)
Filip
Andrei (Scrum Master)

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
protocol: Filip
netidee.at
GitLab Tuwien migration
next release
very well-written backend issues:
- local backend tests
- compilation times #1210 (please create issues first)
content:
- drawing layer names (several ones): https://pull.permaplant.net/1236/files
docu available https://doc.permaplant.net/dev/
branches:
- new dev branch
- rename to mr.permaplant.net
- dev.permaplant.net rename to master.permaplant.net
scrum with Andrei:
- issues
- reviews -> later
- (manual) e2e tests -> later Christoph+Filip
last sprint before release
create issues:
- rework notification system (Jannis+Andrei)
- Jannis: raw SQL
sprint plan

Tasks for Everyone

To be done until Friday 12.04.2024:

update your README.md in submissions repo
buddy talk: documentation improvements
approve meeting PR #1254
request and approve for requested reviews requested reviews
do/update sprint plan

Individual Tasks

To be done until Friday 12.04.2024:

Daniel: finish timeline, drawing, meeting refactor layers
Filip: GitLab, network problem
Jannis: creation times, how to name branches, tutorial for layer creation (creation/update metadata + what interface should any layer have), review DB Doku from Christoph, notification profilen
Moritz: meeting refactoring, heatmap rebase, issues restructure, write if all stale branches can be removed
Christoph: german name issue, SQL heatmap benchmark, hierarchy PR
Lukas: documenting how to create+test layers, investigate panning performance
Andrei: create issues
Yvonne: find manually inserted data in CSV

Meeting Notes

We will apply for netidee funding. If interested write an email to Markus&Yvonne. If necessary, we will have a meeting to further discuss details. Needed for application is a 15 second video per person, to see each team member in the team.

Migration to GitLab: everyone can log in and play around already. This week are all Issues & PRs still in Github.

Release: only small bugs missing.

In future we will have two main branches:

master: stable branch for releases (mostly bug fixes)
dev: development branch (bigger features, most things)

The small feature branches stay the same and usually have the dev branch as target

When creating PRs: Link to issue and add small summaries to PRs to help Reviewers
When doing reviews: mention what you did as reviewer.

Individual tasks (also see above):

Andrei: part of the meetings for Reviews to make working together more efficient in near future.
Lukas proposition: clean up the branches, that are stale and not of use anymore.
Layers: Small refactorings and features can be done in parallel, and refactoring and doc is positive. Daniel organizes meeting about this.

Tasks for everyone (see above):

Fill up submission repository.
For this week do README.md.
Next week TISS.txt.

Meeting 15.04.2024

Attendees

Markus
Yvonne
Christoph
Moritz
Lukas
Daniel
Jannis

Not here:

Filip

Sick:

Andrei (Scrum Master)

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
protocol: Daniel
release v0.4.0 done
GitLab Tuwien migration
https://github.com/supabase/index_advisor
scrum with Andrei:
- issues
- reviews -> later
- (manual) e2e tests -> later Christoph+Filip
create issues:
- rework notification system (Jannis+Andrei)
- Jannis: raw SQL
sprint plan

Tasks for Everyone

To be done until Friday 19.04.2024:

create or update TISS.txt in submissions repo
buddy talk: scoping with mistakes
approve meeting PR
request and approve for requested reviews requested reviews
do/update sprint plan

Individual Tasks

To be done until Friday 19.04.2024:

Daniel: finish timeline, drawing
Filip: GitLab migration
Jannis: creation times, create issues: (1) tutorial for layer creation (creation/update metadata + (2) what interface should any layer have), (3) notification profilen (4) drawing layer db design, (5) unify layer design
Christoph: SQL heatmap benchmark, hierarchy PR
Lukas: documenting how to create+test layers, create issues: investigate performance (profile)
Moritz: heatmap rebase, meeting refactoring, issues restructure, write if all stale branches can be removed
Andrei: create issues

Meeting Notes

great job with release, please rebase your PRs
christoph asked if properties should be able to get overwritten in child ranks of plants -> will be discussed in separate meeting. Christoph and Lukas should attend.
- automatic hierarchy based on unique name
- usually no new properties or plants (apart from adding to CSV)
drawing layer PR will be created so that handling can be tested
groupfolder for nextcloud images has to be implemented, so that images on one map can be shared between different users
we shouldn't have to many different tasks in progress but always enough issues created to always have enough for next sprints

Meeting 22.04.2024

Next meeting 6.5.2024 with presentation from Andrei about GitLab/Scrum

Attendees

Markus
Yvonne
Christoph
Moritz
Lukas
Jannis
Daniel (Protocol done)
Andrei (Scrum Master)

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
protocol: Christoph
next meeting in 2 weeks
next release in 3 weeks
Köln Vortrag
tasks for everyone:
1. TISS
2. short mid-term presentation (Moritz already done)
3. case study
use cases: relations&heatmap
- environmental factors
TUgitLab migration
scrum with Andrei next week:
- issues
- reviews
(manual) e2e tests
sprint plan
(after general meeting): redesign frontend&store
- 3 categories []
- sub-objects #1304

Tasks for Everyone

To be done until Tuesday 23.04.2024:

approve meeting PR
TUgitLab "Profile": set Avatar picture
TUgitLab set "Emails -> Add new email" with the public email address you used on GitHub and confirm that email
TUgitLab set "Notifications -> Global notification level" to watch, so that you will get emails in future from activity
TUgitLab "SSH Keys": add ssh key
tick yourself in #1295
update/clarify your issues

Break for any GitHub activity to migrate to GitLab starts: Wednesday 24.04.2024 14:00. From 25.04.2024 on we use GitLab.

To be done until Friday 26.05.2024:

create first research question with intro in submissions repo (in GitLab)
get used to GitLab (video tutorials etc.)

To be done until Friday 03.05.2024:

buddy talk: presentation topic
get PRs done
socratic questioning with at least two questions for research questions, see unterlagen/socratic_questioning.md
cleanup/clarification of all currently assigned issues
request and approve for requested reviews requested reviews
do/update sprint plan

Individual Tasks

To be done until Friday 03.05.2024:

Filip: GitLab migration
Daniel: finish timeline, drawing, create new layer
Jannis: creating layers, create issues: (1) tutorial for layer creation (creation/update metadata + (2) what interface should any layer have), (3) notification profilen (4) drawing layer db design, (5) unify layer design
Christoph: SQL heatmap optimization, hierarchy, delete plants, subtyping
Lukas: use cases, create issues: investigate performance (profile)
Andrei: categorize and improve issues, copy&paste use case
Moritz: refactoring
Christoph: heatmap questions

Meeting Notes

Next meeting in 2 weeks
Next release in 3 weeks
Andrei will give his presentation in 2 weeks

Markus did a short presentation about his current research topic 'configuration', also in the context of Elektra and PermaplanT. It's important for presentations and our thesis to present a domain specific question in the context of our scientific topic.

Everyone should do a short presentation (2-3min, 2-3 slides) to introduce themselves and show the others what they are working on. Topics could be about e.g. about your research questions, some code, some tooling, the case study or a benchmark. Furthermore, everyone should use PermaplanT for your use case, e.g. plan your garden.

It would be great if everyone could give demos from time to time.

Relation layer and heatmap show environmental constraints. Considering other plants and environmental factors (hydrology, soil, etc.). icons and text will describe relations in the relation layer, e.g. "Spinach should not be planted after spinach" (crop rotation).

Socratic questioning: While reviewing the research question PRs for each review take at least two socratic questions (see unterlagen/socratic_questioning.md).

Lukas talked about the Brush feature. The brush drawing might need pixels to make it work like in paint. But we could use the border around these pixels to have the polygon we need.

Bug fixes should target master other developer should target the dev branch. In the future this should also be indicated by labels in issues.

Meeting 06.05.2024

Attendees

Markus
Yvonne
Moritz
Lukas
Daniel (Protocol done)
Andrei (Scrum Master)

Came late:

Jannis

Not here:

Christoph (Protocol done)

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
protocol: Lukas
short mid-term presentation (Andrei)
- Product Owner: Yvonne&Markus
- Scrum Master: Andrei&Markus
TUgitLab migration
BBB: everyone is admin now
demos from Daniel
- brushes
- creation of layers
which (docker) dev setups are used?
- 2x dev container (or more?)
- 2x docker+backend/frontend local
- 1x pure local (no docu needed?)
next presentation: Daniel
scrum with Andrei next week:
- 45 issues in progress?
- reviews
new burndown chart
refactoring frontend&store (conclusion was written down in issue)
next release (postponed)
(manual) e2e tests (postponed)

Tasks for Everyone

To be done until Friday 10.05.2024:

buddy talk: presentation topic
approve meeting PR
get MRs done
cleanup/clarification of all currently assigned issues
request and approve for requested reviews
add tasks to burndown chart

Individual Tasks

To be done until Friday 10.05.2024:

Lukas: issues hydrology, toolbar refactoring (dev), merge master into dev, hydrology
Daniel: finish timeline, drawing, create new layer, (brushes)
Jannis: postponed deletion layers+map, create issues: (1) tutorial for layer creation (creation/update metadata + (2) what interface should any layer have), (3) unify layer design
Andrei: categorize and improve issues, remembering viewing state (copy&paste)
Moritz: grid UC finish, base layer image offset, avatar GitLab, (map deletion), selection+deselection refactoring

Not here:

Christoph: SQL heatmap optimization, hierarchy, delete plants, subtyping

Meeting Notes

Andrei presented a software development process: Agile is a mindset for software developement and Scrum is the framework implementing it. It defines at least three roles (Product Owner, Scrum Master, Devs), three Artifacts (Product Backlog, Sprint Backlog, Increment) and five events (Sprint, Sprint Planning, Daily Scrum, Sprint Review, Sprint Retro. MRs, issues and requested reviews should always be assigned to someone to then see the todos at the top left in Gitlab. Labels should also always be set at issues & MRs for everyone getting a good overview.

Iterations are set as a property and when an issue is not done the iteration automatically increases at the end. Sprints and dailies are mixed in PermaplanT because of only weekly meetings. Big issues describing big parts of use cases can be used to organize and link together small issues which should be easily done in one week and actually describe/represent the work to be done.

The migration to GitLab worked out quite smoothly issues in the pipeline are discussed which were mostly already existed in the past but not visible due to missing or bad error handling. Some changes in the submissions repo were lost but everyone can push them again because they should exist locally.

Daniel presents the current state of the brush feature as a demo. It is already possible to mark/create areas using the brush in the draft. Together with Jannis he also demoed the creation of new layers which is already possible for drawing layers in their draft.

Refactoring and implementations about environmental factors should be merged to dev and everything else should be merged to master. Master is merged into dev weekly. (Lukas for upcoming week)

Everyone should create issues for himself before the weekly meeting which represent upcoming work. Andrei is always creating issues after the weekly meetings for everyone for things discussed in the meeting.

Meeting 13.05.2024

Attendees

Markus
Yvonne
Jannis
Moritz
Lukas (Protocol done)
Daniel (Protocol done)
Andrei (Scrum Master)

Cannot come:

Christoph (Protocol done)

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
protocol: Jannis
presentation next week: Jannis
CI
- Cannot create maps on mr.permaplant.net
- CI sometimes rerun
- mdbook crashes? network problems?
Daniel Presentation
- Selectable, resizeable, disturbable (canBeDistorted) and rotatable
scrum with Andrei:
- issues
- reviews
- Task Board
- next meeting: 20th of May (Pfingsmontag)

Not Yet Discussed

refactoring frontend&store (conclusion was written down in issue)
next release
JSON in database
GitLab "please merge" only if:
- 2 reviewers
- all threads solved
add more manual and automatic e2e tests

Tasks for Everyone

To be done until Friday 17.05.2024:

buddy talk: use case
approve meeting MR
get MRs done
request and approve for requested reviews
create/update issues for yourself and assign to next iteration

Individual Tasks

To be done until Friday 17.05.2024:

Moritz: base layer image offset, avatar GitLab, postponed map deletion (frontend), selection+deselection refactoring
Jannis: postponed deletion layers+map (backend), create issues: (1) tutorial for layer creation (creation/update metadata + (2) what interface should any layer have), (3) unify layer design, presentation
Lukas: toolbar refactoring (dev), merge master into dev, hydrology clarification+issues
Daniel: finish drawing UC (tests etc.), create new layer, brushes
Andrei: categorize and improve issues, remembering viewing state (copy&paste)

Cannot come:

Christoph: SQL heatmap optimization, hierarchy, delete plants, subtyping

Meeting Notes

Database logging improvements needs to improve to help debug the MR server.
Some DB errors seem to be swallowed.
Jannis+Filip will work on this.
Daniel held a presentation on Konva and the refactoring of selection elements on our map.
We might have a performance problem with 10.000 elements in the editor, Konva is not the bottleneck.
We need further profile the code to find out if more finegrained control over the rerendering of components in the map is needed. It may be necessary to rewrite the map in a more imperative style.
Jannis presents next week (20.5) about performance of SEE focusing on the profiling setup.

Meeting 20.05.2024

Attendees

Markus
Yvonne
Moritz
Jannis (Protocol done)
Lukas (Protocol done)
Daniel (Protocol done, Presentation done)
Andrei (Scrum Master, Presentation done)
Christoph (Protocol done)

Only in the beginning:

Filip

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
protocol: Moritz
CI dev issues (Filip)
next release (Filip)
presentation: Jannis
next presentation: Christoph
finish line: Daniel & Moritz
GitLab "please merge" only if:
- 2 reviewers
- all threads solved
add more manual and automatic e2e tests
scrum with Andrei:
- issues
- reviews
- Task Board
refactoring frontend&store:
- Lukas refactors side bar
- Daniel does other refactorings

Not Yet Discussed

JSON in database

Tasks for Everyone

To be done until Friday 24.05.2024:

buddy talk: logical architecture
approve meeting MR
get MRs done
request and approve for requested reviews
create/update issues for yourself and assign to next iteration

Individual Tasks

To be done until Friday 24.05.2024:

Jannis: create issues: (1) tutorial for layer creation (creation/update metadata + (2) what interface should any layer have), (3) unify layer design, presentation
Moritz: base layer image offset, finish PRs: group vs. layers
Lukas: toolbar refactoring (dev), clarification+issues
Christoph: SQL heatmap optimization, hierarchy, delete plants, subtyping, presentation
Daniel: finish drawing UC (tests etc.), create new layer, brushes
Andrei: categorize and improve issues, remembering viewing state (copy&paste), merge master to dev

Meeting Notes

More E2E tests should be implemented for existing as well as new features. If this is not possible, describing a manual test is also a viable alternative. Add manual tests to doc/tests/manual/protocol.md

There are subtle differences between the done and closed issue status. Usually issues should be closed once the corresponding PR is merged.

Blocked issues are either marked with links (preferred) or the scoped label blocked (if it is blocked because of e.g. waiting for input which is not reflected as an issue).

Meeting 27.05.2024

Attendees

Markus
Yvonne
Daniel (Presentation done)
Andrei (Presentation done)
Jannis (Presentation done)
Christoph
Lukas

Came later:

Moritz (Presentation done)

Only in the beginning:

Filip

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
presentation: Christoph
protocol: Daniel
CI dev issues (Filip)
next release
next presentation: Lukas
add more manual and automatic e2e tests
JSON in database
scrum with Andrei:
- issues
- reviews
- Task Board
refactoring frontend&store:
- Lukas refactors side bar
- Daniel does other refactorings
- Moritz layers -> groups

Tasks for Everyone

To be done until Friday 31.05.2024:

buddy talk: logical architecture
approve meeting MR
get MRs done
request and approve for requested reviews
create/update issues for yourself and assign to next iteration

Individual Tasks

To be done until Friday 31.05.2024:

Moritz: base layer image offset, finish PRs: group vs. layers
Christoph: SQL heatmap optimization, hierarchy, delete plants, subtyping
Daniel: create new layer, brushes, refactoring, cleanup issues and UC (tests)
Jannis: layer management, notes, offset, create issues: (1) tutorial for layer creation (creation/update metadata + (2) what interface should any layer have), (3) unify layer design, merge master to dev
Lukas: refactoring (dev), clarification+issues
Andrei: categorize and improve issues, remembering viewing state (copy&paste)

Meeting Notes

Christoph presented
- how to investigate performance issues via profiling
- how he was able to improve the heatmap algorithm
there are few open issues that should be done until tomorrows release
we should disable flipping of plants. should be possible by using "flipEnabled" flag supported by konva transformer
pipeline of "LayerManagement" is failing constantly. Daniel and Jannis will fix it and also test functionality of feature.
Lukas will do presentation about profiling with Firefox next week

Meeting 03.06.2024

Attendees

Markus
Yvonne
Jannis (Presentation done)
Moritz (Presentation done)
Christoph (Presentation done)

Cannot come:

Lukas
Daniel (Protocol done, Presentation done)

Did not come:

Andrei (Presentation done)

Only in the beginning:

Filip

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
CI dev issues (Filip)
check-in
protocol: Jannis
release done!
dev branch revisited
- master -> dev no stable migrations
- get dev merged soon (June?)
documentation can always be improved (any PR)
all questions in GitLab should've been answered (2.6.2024)
060.030 How to Bachelor- und Masterarbeiten
Life Meeting July/August?
next presentation: Lukas (Filip)
Task Board

Tasks for Everyone

To be done until Friday 07.06.2024:

buddy talk: status? support? ("Wo stehst du gerade? Wie kann ich dich unterstützen?)
approve meeting MR
get MRs done
request and approve for requested reviews
create/update issues for yourself and assign to next iteration

Individual Tasks

To be done until Friday 07.06.2024:

Daniel: brushes, refactoring, cleanup issues and UC (tests)
Jannis: offset, create issues: (1) tutorial for layer creation (creation/update metadata), (2) what interface should any layer have), (3) unify layer design
Christoph: SQL heatmap optimization, hierarchy, delete plants, subtyping
Moritz: base layer image offset, finish PRs: group vs. layers
Lukas: clarification+issues
Andrei: categorize and improve issues, remembering viewing state

Meeting Notes

Dev branch exists because heatmap is not done and cannot be merged into master yet. Christoph brought the performance to an acceptable level already (0.5s). Juni/july dev branch should be done.
Dev into Master: Open MR of branch originating from dev, which merges master into dev.
Backend has been merged by Jannis frontend has conflicts. Lukas will fix it.
Get together in summer, poll about who/when/details follow.

Meeting 10.06.2024

Attendees

Markus
Yvonne
Jannis (Protocol done, Presentation done)
Moritz (Presentation done)
Andrei (Presentation done)
Lukas

Not here:

Christoph (Presentation done)
Daniel (Protocol done, Presentation done)

Only in the beginning:

Filip (cannot come next time)

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
CI dev issues (Filip)
Perma.Fest: dev und master branch
- https://www.permakultur-austria-akademie.at/permakultur-austria-feiert/
availability Markus: from Thursday on
protocol: Moritz
next presentation (in two weeks): Filip
presentation: Lukas
- create issues
- upload presentation
Life Meeting July/August?
thesis
- terminology
- acronyms
- abstract should consist of: context, problem, methods, and results
- method/results
dev branch revisited
- minimalize merges targeting master
- refactoring only in dev
- reformatting on both
Moritz fragen
UI guidelines
- rightclick for paths
documentation can always be improved (any PR)
buddy talk: status? support? ("Wo stehst du gerade? Wie kann ich dich unterstützen?)
Task Board

Tasks for Everyone

To be done until Friday 14.06.2024:

please upload portraits for landingpage
buddy talk: Review https://survey.permaplant.net/ together (Please review early: Survey already starts this iteration!)
approve meeting MR
get MRs done
request and approve for requested reviews
create/update issues for yourself and assign to next iteration

Individual Tasks

To be done until Friday 14.06.2024:

Daniel: brushes, refactoring, cleanup issues and UC (tests)
Jannis: offset, create issues: (1) tutorial for layer creation (creation/update metadata), (2) what interface should any layer have), (3) unify layer design
Moritz: base layer image offset, finish PRs: group vs. layers, get UC done, test cases
Lukas: clarification+issues, methodology, prepare sending out+stat analysis
Andrei: categorize and improve issues, remembering viewing state

Cannot come:

Christoph: SQL heatmap optimization, hierarchy, delete plants, subtyping

Meeting Notes

Permaplant will be presented at a permaculture convention in Vienna this Sunday June 16. The heatmap should be in working order at this date and all Permaplant devs are invited to join the event (https://www.permakultur-austria-akademie.at/permakultur-austria-feiert/).

The Permaplant devs are invited to an in person meeting at Yvonnes and Markus' property in Burgenland.

Meeting 17.06.2024

Attendees

Markus
Yvonne
Moritz (Protocol done, Presentation done)
Lukas (Presentation done)
Christoph (Presentation done)
Daniel (Protocol done, Presentation done)

Not here:

Andrei (Presentation done)

Cannot come:

Jannis (Protocol done, Presentation done)
Filip

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

Agenda

09:00 start
welcome
protocol: Christoph
next presentation (in July): Filip
Perma.Fest: news
- https://www.permakultur-austria-akademie.at/permakultur-austria-feiert/
survey: please share, forward
all MRs to dev branch
use case clarification, DOD, e2e test cases
Task Board

Tasks for Everyone

To be done until Friday 21.06.2024:

buddy talk: choose your topic
approve meeting MR
get MRs done
request and approve for requested reviews
create/update issues for yourself and assign to next iteration

Individual Tasks

To be done until Friday 21.06.2024:

Daniel: UC done (tests)
Moritz: base layer image offset, finish PRs: group vs. layers, get UC done, test cases
Christoph: SQL heatmap fixes+optimization
Lukas: clarification+issues, reminding survey, stat analysis

Was not here:

Andrei: categorize and improve issues, remembering viewing state

Cannot come:

Jannis: offset, create issues: (1) tutorial for layer creation (creation/update metadata), (2) what interface should any layer have), (3) unify layer design

Meeting Notes

There was great interest and positive feedback about PermaplanT at Perma.Fest. Everybody should please fill out the survey at https://survey.permaplant.net/ and also share it with other people. There is a checklist in doc/usecases/README.md that should be used to decide whether a use case is completed. Everybody should plan their issues in advance, so they always have unblocked issues to work on.

Meeting 24.06.2024

Next meeting 15.07.2024.

Attendees

Markus
Yvonne
Christoph
Lukas
Andrei
Moritz
Filip

Not here:

Jannis

Cannot come:

Daniel

Buddies

Daniel & Andrei
Moritz & Christoph
Jannis & Lukas

After one week, new buddies:

Andrei & Christoph
Jannis & Lukas

Agenda

09:00 start
welcome
protocol: Moritz (last protocol)
this time: 3 weeks iteration until 15.07.2024
next meeting (short check-in) with Yvonne on 01.07.2024
last presentation (22.July): Filip
version upgrades July (Debian, Rust?, nodejs?)
buddy talk?
structure of thesis
console.log
ReinSaat
survey: please share, forward
SQL constants?
push to submissions should work now
dev:
- all MRs to dev branch
- dev branch migrations
- reset dev database if migrations are incompatible
architecture/split stores?
tasks for anyone
Task Board
Thursday 14:00 heatmap meeting (Lukas until 15:30)

Tasks for Everyone

To be done until Thursday 27.06.2024:

approve meeting MR
review architecture
do reviews, especially for Moritz and Daniel

To be done until Friday 12.07.2024:

buddy talk: choose your topic
get MRs done
request and approve for requested reviews
create/update issues for yourself and assign to next iteration

Individual Tasks

To be done until Friday 12.07.2024:

Moritz: finished (base layer image offset, finish PRs: group vs. layers, test cases, get UC done)
Christoph: hierarchy
Lukas: clarification of issues, stat analysis, crop rotation
Andrei: categorize and improve issues, remembering viewing state, (maybe afterwards copy&paste)
Yvonne: issue about avatars

Was not here:

Jannis: offset, go through issues, create issues: (1) tutorial for layer creation (creation/update metadata), (2) what interface should any layer have), (3) unify layer design

Cannot come:

Daniel: finished (UC done, tests)

Meeting Notes

This weeks iteration will span 3 weeks. Major upgrades to the infrastructure, specifically to our infrastructure, such as CI Runners are planned. Upgrades to Rust and NodeJS are unclear.

A few notes on the structure of the thesis:

Either do Background OR do related work. Both are usually not necessary, since they both accomplish more or less the same goals in a slightly different manner. Generally, related work should be used for most thesies (Lukas' probably being the only exception).

Cleanly separate Methodology, Results and Interpretation/own opinions.

You may use the official TU-Wien Informatics Thesis-Template, but it is not strictly necessary.

Please don't open merge requests in the thesis-repo for uninteresting changes (e.g. adding the thesis template files). Push those directly to master instead.

Yvonne and Markus met up with the CEO of Reinsaat (the biggest Organic seed Producer in AT) to show the current progress on PermaplanT. They were asked to forward the survey to their customers.

Since we already have all plants from Reinsaat in the DB, the idea is that in the long term PermaplanT users should be able to directly order Reinsaat-seeds from the app.

Reinssat also considered using Permaplant for their internal garden planning tasks.

All PermaplanT members are asked to forward the survery to as many people as possible.

Merge requests should target dev by default. Merging to master should only happen in rare exceptions.

Meeting 27.06.2024 - Heatmap

Attendees

Markus
Yvonne
Lukas
Christoph (protocol)

Agenda

Heatmap rework (traffic light system)
Heatmap layers

Meeting notes

General

The heatmap visuals will be changed from a red to green color gradient to a traffic light system (red, orange, green). Each cell has an opacity level between 0% and 80%, with following cases:

A cell should be 0% opaque (no color) if there is no data for it.
Red means the cell is completely unsuitable for a plant.
Orange means the spot is not ideal according the available data.
Green indicates a favorable space.
Black indicates a space occupied in the future, see #1472

The opacity depends on the environmental factor. The rules for combining several environmental factors are:

The worst color grade is taken.
Opacity should be increased for each factor present in the same space.

Examples:

If one layer is orange with 60% opacity and another is red with 50% opacity then the cell should be red with about 70% opacity
If two layers are red with 50% opacity then the cell should be red with about 70% opacity

(Actual math of opacity is to be discussed)

Example scenarios for colors:

Red is caused by the shading being off by 2 or more levels or the moisture class being wrong
Orange is caused by an antagonistic spatial relationship, the shading being off by 1 level or being negatively affected by previously planted crops (crop rotation)

All mentioned values should be configurable via a database table. Even the colors should be configurable for accessibility.

Shade layer

'Permanent deep shade' should be removed.
If there is no shading drawn in a cell it should count as 'no shade' (full sun).
Shading calculation should consider a plant's light_requirement and shade
For the shading calculation a cell being darker than the light_requirement is always worse, but it being lighter is fine
Influence of shadings should drop of a bit at the edges (the edges should have lower opacity)

Hydrology layer (= moisture layer)

If there is no moisture specified for a cell, it should not be considered in the heatmap

Plant spatial relations

Currently the influence starts to drop off at the 'edge' of the plant
There has been some discussion that the influence should start dropping off a little earlier
Currently only spatial relationships are considered for the planting date (while planting)
In the future there will be a new (optional) column time_to_harvest, which will determine when the plant will be removed (which is additional to life_cycle, to be used when no time_to_harvest is available). The removed_on date will be set by adding a plants time_to_harvest to its added_on date after planting a plant.
When planting a new plant, the whole interval from added_on to removed_on should be considered, not just added_on
If no removed_on date can be determined then only the added_on date is considered (this is the case for 'endless' plants or trees)

Crop rotation

Crop rotation doesn't have influence over a distance, only spatial relation has influence over a distance.

Meeting 15.07.2024

Attendees

Markus
Yvonne
Lukas
Christoph
Stefanie
Jannis

Missing:

Andrei

Planned Holidays:

Filip

Goodbye:

Moritz
Daniel

Buddies

Stefanie & Christoph & Andrei
Jannis & Lukas

Agenda

09:00 start
welcome Stefanie
goodbye Moritz and Daniel
protocol: Lukas
live meeting poll
- 1. / 11.8.
- 1. / 18..8.
- 1. / 25.8.
short report from heatmap meeting
If you are shooting yourselves in the foot constantly, fix the gun
version upgrades July (Debian, Rust?, nodejs?)
buddy talk?
thesis
dev:
- all MRs to dev branch
- dev branch migrations
- reset dev database if migrations are incompatible
Task Board
last presentation (22.July): Filip

Tasks for Everyone

To be done until Friday 19.07.2024:

live meeting Umfrage abstimmen
approve meeting MR
buddy talk: choose your topic
get MRs done
request and approve for requested reviews
create/update issues for yourself and assign to next iteration

Individual Tasks

To be done until Friday 19.07.2024:

Stefanie: onboarding
Jannis: complete MRs, go through issues, create issues: (1) tutorial for layer creation (creation/update metadata), (2) what interface should any layer have), (3) unify layer design
Christoph: hierarchy
Lukas: stat analysis, crop rotation

Was not here:

Andrei: categorize and improve issues, remembering viewing state, (maybe afterwards copy&paste)

Meeting Notes

We welcomed Stefanie.

Moritz and Daniel were given a warm shower in their last meeting for PermaplanT.

The date for the Live Meeting will be decided via a poll. Arriving with public transport would be preferred, pickup from nearby places (Weppersdorf) is possible.

There was a heatmap meeting and there are meeting notes for it.

For the plant hierarchy implementation Christoph will write a concept and based on that a follow-up meeting will be held.

Dev Setup MR should be done before Stefanie starts with her onboarding. Jannis will assist Stefanie with her setup.

Stefanie will be buddy of Christoph and Andrei and can contact everyone for questions.

Meeting 22.07.2024

Attendees

Markus
Lukas (Protocol done)
Christoph
Stefanie
Filip
Andrei

Sick:

Yvonne
Jannis

Buddies

Stefanie & Christoph & Andrei
Jannis & Lukas

Agenda

09:00 start
presentation Filip
protocol: Christoph
technical texts:
- explain step by step (maybe backtracking from goal)
- clear terminology, don't use words you don't need (e.g. latency, ...)
- focus on one thing and explain that properly
- explain data
fundamentals of science:
- method (reproducible or at least clear what was done)
- results (from method, without opinion)
- findings
standards for scientific texts:
- related work should compare
- make "Why?" clear
- advertise your contributions
- write about future work
improvements of UX (focus group)
issue:MR should be 1:1 and always connected
Task Board

Tasks for Everyone

To be done until Friday 26.07.2024:

last chance, please vote for live meeting
create a MR on submissions with a (short) technical text (review next week)
approve meeting MR
buddy talk: technical text
get MRs done
request and approve for requested reviews
create/update issues for yourself and assign to next iteration

Individual Tasks

To be done until Friday 26.07.2024:

Stefanie: rework usecases
Christoph: hierarchy
Lukas: crop rotation
Andrei: categorize and improve issues, remembering viewing state

Sick:

Jannis: complete MRs, go through issues, create issues: (1) tutorial for layer creation (creation/update metadata), (2) what interface should any layer have), (3) unify layer design

Meeting Notes

Filip held a presentation about PermaplanT CI explaining the overall architecture and how Jenkins, Docker and Ansible are used.

Thesis

Your thesis should include both a technical text as well as a scientific text.

Technical text

Say one thing as clearly as possible. Every technical person with computer science background should be able to understand it. It might help to backtrack: "What do you have to explain to come to this point?". Then write the minimum amount of text to arrive at your point. First explain the most basic parts and then continue building upon it. You can assume the reader has the general knowledge of someone who studied IT, e.g., you don't have to explain HTML and Javascript but you should explain Konva (if it is relevant). The terminology should be as clear as possible and consistent to the PermaplanT glossary. Always use the same words, don't use synonyms. One trick is to write a technical text and then come back to it weeks later to check if it's still understandable. Alternatively have someone review it.

Scientific text

Explain your method and results, optionally present your findings. Your method should be reproducible. The minimum standard of methodology is that other people understand what you did. For reproducability document your test environment, including version numbers of used software. Findings are the objective result of applying the described method. Other people should be able to come to the same conclusion based on your findings.

For related work do a technical comparison.

Your contributions should only be mentioned in the introduction (not in methodology and results).

It is very important to be consistent with your terminology.

Meeting 29.07.2024

Attendees

Markus
Lukas (Protocol done)
Christoph (Protocol done)
Stefanie
Filip
Andrei
Jannis
Yvonne

Buddies

Stefanie & Christoph & Andrei
Jannis & Lukas

Agenda

09:00 start
welcome round: super power
protocol: Stefanie
nodejs version upgrades (20.16)
quality goals
changelog keywords
review round technical texts:
- review list
- reverse engineering of text
next release
- new news
- make news scrollable
- yearly tasks: change 2023 -> 2024
shadings coordinations
live meeting probably 25.08.
improvements of UX (focus group) -> meeting with Stefanie
Task Board

Tasks for Everyone

To be done until Friday 02.08.2024:

review MRs on submissions (see unterlagen/review_checklist.txt in submissions)
buddy talk: technical text (review)
update to nodejs 20.16 on your machine
approve meeting MR
request and approve for requested reviews
get MRs done
create/update issues for yourself and assign to next iteration

Individual Tasks

To be done until Friday 02.08.2024:

Filip: do release
Jannis: complete MRs, hydrology&soil type backend implementation
Stefanie: UI testing master+dev, meeting end of week
Christoph: finish heatmap (handover to Lukas)
Lukas: implement attributes
Andrei: categorize and improve issues, remembering viewing state

Meeting Notes

Default Branch Changed to dev

So that the auto-close issue works for most cases, dev is now the default branch.

"Boring" technical stuff

Nodejs version update coming. Update your dev env with version 20 this week.

Quality goals

We can always change endpoints as needed.
Goals have different priorities. Only when you can achieve one goal on the top, go to the next. Prioritize usability a little more :)
Added new keywords for the changelog.md for specific changes (migration, scraperdata, endpoint, CI).

Review round - Technical text

Today every technical text should be ready. Undraft the current MRs. This week we will review these texts to help and improve your own writing as well. There is a review checklist to go over to check quality. Circle terms and then make arrows indicating 'dependencies' in the text to make clear which parts are wrong order or are not defined. You don't need to explain terms commonly known in computer science, but you have to explain the context in which you're using it. Everyone needs to read all of the technical texts.

You can update your MRs after every review as needed to get several useful reviews.

Release this week

If you want your image to be on the landing page, send it to Yvonne. A new news entry will be added, news section needs to be a little more space-efficient -> Slider. Master needs to be manually tested before the release.

Shading

Christoph and Lukas are collaborating on this issue. Christoph does the starting work and Lukas is gonna finish it.

Hydrology and soil type are gonna be added as new layers. Soil type is going to be part of the heatmap concept.

Mockups

Garden Planter

Summary

Garden Planter is a gardening app that allows users to plan their garden by dragging and dropping plants into rectangular beds on a fixed grid. Available for Android, iOS, and the web.

It includes detailed information about different plant varieties and provides helpful growing details, such as watering and temperature tolerance, for each plant. It also has a feature that indicates whether two plants can grow well together by displaying a red or green mark. In addition, Garden Planter allows users to customize the size of the grid cells based on the specific needs of each plant, and to set frost dates to help with planning. The app's user interfase is clear and user-friendly, with custom icons and plant pictures to help users easily navigate the app.

Company: Percula LLC

Note: Web app currently only Beta version

Differences

PermaplanT is a gardening app that offers more variety via permaculture planning, which is not available in Garden Planter. PermaplanT also includes more complex input parameters, such as soil type, shade, and wet/dry conditions, to provide more accurate results for companion/antagonist. In summary, PermaplanT has more features than Garden Planter and should lead to more diverse ecosystems for permaculture gardens.

Title: Smart Gardener

Summary

Smart Gardener is a Web gardening app that allows users to plan their garden by dragging and dropping plants into rectangular, circular, and rotated rectangular beds. It also has a feature that allows users to create and cover certain plants in shade. However, the app has a poorly designed and outdated user interface, and it does not have a feature that indicates whether a plant is a good match for a particular location.

Similarities

Layer activation and visibility (but list of plants etc. is shown somewhere else).

Differences

Smart Gardener does not have many of the functionalities offered by PermaplanT, such as checks to determine whether a plant is well-suited for a particular location based on factors such as sun, soil, companion/antagonist, and time of year. Overall, Smart Gardener does not offer as many functionalities as PermaplanT and is not as comprehensive in its approach to planning and maintaining a permaculture garden.

Veggie Planner

Summary

Veggie Garden Planner is a mobile app that allows users to design their gardens by dragging and dropping plants onto a canvas, without the constraints of a fixed grid. The app provides general information about each plant and indicates the relationship between plants that are placed close together on the canvas. In addition, it displays a tabular overview of the relationships between all of the plants that have been placed on the canvas. However, the app's user experience could be improved, as it requires users to add plants to their list before they can be placed on the canvas.

Differences

Veggie Planner offers more flexibility than other gardening apps, but it is again not as feature-rich as PermaplanT, which includes permaculture planning capabilities in addition to flexible plant placement and dynamic plant relationships.

Fryd

Summary

Fryd is a web, Android, and iOS garden planning app that requires authentication to use. It offers various finished garden plans and allows users to choose the type and size of their garden. Users can also choose the shape of their garden beds and indicate the type of soil and shade in their garden. The app includes features such as undo/redo, zoom, and the ability to add landscape elements such as houses, trees, and bushes. However, through personal experience, it is not quite performant as dragging some elements can show visible delays. In addition, it is not clear whether adding different landscape elements and shading affects the relationship indicator between plants.

Similarities

Zoom with scrolling
Drag&Drop from right window (In PermaplanT windows should be minimizable)
Resize (PermaplanT has indication of width/length and not so big blue handles)
Automatic room consumption of plants
Symbols with connections to indicate good/bad relation between plants (PermaplanT additionally has visual indication for good/bad places)

Differences

In terms of their goals, both apps aim to enable planning for a diverse garden and have similar features. However, the PermaplanT app will have more parameters to customize the garden and landscape, which can indicate a more accurate relationship between different plants. Fryd:

doesn't have proper layers
no copy & paste
ways are covered by beds

In PermaplanT:

plants can be outside of beds -> no rotation of beds needed
concept for menu should be simpler
doesn't have rows of plants (but only areas if chosen by user)
there is no "magic stick"

powerplant

Summary

powerplant is a FLOSS MIT-licensed web app, which is inactive since a few years.

Similarities

technology: react
goals: yield

Differences

focus on offline functionality and less on collaboration
focus on beds
quite different in technology: uses JavaScript instead of TypeScript/Rust

Interesting Ideas

provides an easy to follow schedule for planting, transplanting, and harvesting
gives suggestions which plants should be grown in which environment - location, climate, …
see here for several other even longer inactive projects

Release Procedure Documentation

This document describes what needs to be done for a release.

check if all issues labelled release critical are fixed
check if jenkins master pipeline succeeds
run external link check (change follow-web-links in book.toml and do mdbook build)
fix real security problems unfortunately npm audit --omit=dev fix does too much and too little, cargo deny check seems to be more helpful
remove all WIP migration comments from migrations Find all WIP migrations with grep -rl "WIP migration" backend/migrations
check/improve reformatting
update mergedDatasets.csv
manually test dev.permaplant.net according to protocol
build https://build.libelektra.org/job/PermaplanT-Release/
git tag -s vX.X.X
git push --tags
create release PR to pump versions and new section in Changelog
write announcement

Yearly tasks

increase year in LICENSE

Research

Nextcloud Integration

Authentication Setup

Keycloak and Nextcloud run as separate services. Users are created in Keycloak instead of in Nextcloud/PermaplanT and users can then log in via Keycloak. In the PermaplanT frontend the user is redirected to the Keycloak login screen. They are prompted for their credentials and then they get redirected back to the PermaplanT web application. From then on all requests are authorized via JWT. We use the recommended variant which is Authorization Code Flow with PKCE. This and other variants are described in detail in the OAuth2.0 specification. The backend then validates the tokens and extract roles/user information. The same token is used to fetch resources from Nextcloud.

To enable the OIDC functionality on Nextcloud we installed a plugin called user_oidc developed by Nextcloud. With this plugin OIDC providers can be configured in Nextcloud. After successful configuration the provider appears on the login screen and the user can log in with their credentials from the provider.

Files

WebDAV Protocol

"WebDAV (Web Distributed Authoring and Versioning) is a set of extensions to the Hypertext Transfer Protocol (HTTP), which allows user agents to collaboratively author contents directly in an HTTP web server by providing facilities for concurrency control and namespace operations, thus allowing Web to be viewed as a writeable, collaborative medium and not just a read-only medium." wikipedia

Access Files

Nextcloud implements the webDAV protocol. This means that we can access files in Nextcloud with any webdav client. There are popular file managers like 'Konqueror' from the KDE team and 'GNOME Files' from the GNOME team which implement the webDAV protocol. However webDAV is not exclusive to file managers. In PermaplanT we use a Javascript library named webdav to access files in Nextcloud. For files available on public shares we send the requests directly with axios.

Public shares are directories where a public link is created. The last part of the link is the share token. E.g. for the URL 'https://cloud.permaplant.net/s/2arzyJZYj2oNnHX' the share token is '2arzyJZYj2oNnHX'. This share token can be used as username and password to access files from the directory. Files at the top level as well as files in subdirectories can be accessed using the share token. E.g. when following directory structure is given:

nextcloud_root_dir
├── Documents
│   └── secret-doc.txt
├── Photos
└── Public
    ├── Icons
    │   ├── add.svg
    │   └── delete.svg
    ├── Maps
    │   └── map.json
    └── Pictures
        └── tree.png

and the directory 'Public' is accessed with the share token. All files ('add.svg', 'delete.svg', 'map.json', 'tree.png') in all subdirectories ('Icons', 'Maps', 'Pictures') of 'Public' can be accessed. The path for fetching a file starts at the shared directory, in this case 'Public'. To access the file 'add.svg' following URI is used: 'https://cloud.permaplant.net/public.php/webdav/Icons/add.svg'. The first part: 'https://cloud.permaplant.net/' is the scheme and host for our Nextcloud instance. The next part /public.php/webdav/ is the endpoint used to access files from the public share directory specified by the share token. The share token is given as username and password in the request. The last part 'Icons/add.svg' is the path to the requested file starting from the public share directory.

When we want to fetch add.svg, we use the following request:

curl -X GET -O -u 2arzyJZYj2oNnHX:2arzyJZYj2oNnHX https://cloud.permaplant.net/public.php/webdav/Icons/add.svg

In PermaplanT we use the public shares for data which should be accessible by unauthenticated users. E.g. images on the landing page or icons for plants.

To fetch resources from directories which are not available for the public some form of authentication has to be used. The easiest way to authenticate with the Nextcloud instance is to use the username and password in the request. This is called basic authentication. However, this is not secure when the requests are sent from the browser as this information can be easily sniffed. So we decided to use 'OpenID Connect' for authentication. Details on why we decided to use 'OpenID Connect' can be found in the decision document.

All we need to know here is that requests from authenticated users are populated with the access token in the Authorization header.

Now we can make requests against the '/remote.php/webdav' endpoint. This endpoint enables us to fetch files starting from the root directory of the logged in user. Given the previously defined directory structure we can now access the file 'secret-doc.txt' with the following URI: 'https://cloud.permaplant.net/remote.php/webdav/Documents/secret-doc.txt'

Directory Structure

In the PermaplanT Nextcloud instance we have following directory structure for each user:

PermaplanT/
└── Maps
    ├── map_01
    │   ├── BaseLayer
    │   │   └── base_layer_image.png
    │   └── PhotoLayer
    │       ├── photo1.jpg
    │       └── photo2.jpg
    └── map_02
        ├── BaseLayer
        │   └── base_layer_image.png
        └── PhotoLayer
            ├── photo1.jpg
            └── photo2.jpg

When a PermaplanT map is shared between different users the corresponding Nextcloud directory has to be shared as well. When a directory is shared in Nextcloud it gets added to users root directory (if not configured otherwise). We have to move the newly added directory to the correct place in the hierarchy after it was added.

Each map directory must have a globally unique name to avoid conflicts with shared maps. The name of each map directory is the same as the name of the map in the PermaplanT database. This insures that the name is unique because the name in the database is unique.

The location of public directories does not matter as they are identified by the public share token. They are not visible to all of the users in Nextcloud, so they are not included in the directory hierarchy above.

Shares and Permissions

When we want to add additional members to our PermaplanT map we also have to share the Nextcloud resources with them. To share and manage permissions on Nextcloud directories we generally use Nextcloud Circles. The major difference to groups is that Circles can be created by normal users while groups need higher privileges to manage.

Unfortunately the Circles API is not well documented. The implementation of the API can be found on the corresponding github repository.

First we need to create a Circle. This can be achieved by following API call:

"method": "POST",
"headers": [
  "OCS-APIRequest": true,
  "Content-Type": "application/json"
],
"body": {
  "name": "map_01",
  "personal": false,
  "local": false
},
"scheme":	"https",
"host": "cloud.permaplant.net",
"filename": "/ocs/v2.php/apps/circles/circles"

The name of the Circle is the same as the name of the map. Now the Circle has to be added to the shares for the map directory. This can be done with the OCS Share API which is documented here. Following API call can be used:

"method": "POST",
"headers": [
  "OCS-APIRequest": true
],
"body": {
  "path": "PermaplanT/Maps/map_01",
  "shareType": 7,
  "permissions": 31,
  "shareWith": "<circleId>"
},
"scheme":	"https",
"host": "cloud.permaplant.net",
"filename": "/ocs/v2.php/apps/files_sharing/api/v1/shares"

The argument shareType specifies what kind of share we want to create. The options are:

0 = user
1 = group
3 = public link
4 = email
6 = federated cloud share
7 = circle
10 = Talk conversation

We chose 7 to share the directory with the newly created Circle.

If not specified the permissions for the share are set to 31 which means all. If we want to have more granular control of the permission we can set the permissions parameter to one of these values:

1 = read
2 = update
4 = create
8 = delete
16 = share
31 = all

If we want even more granular permission control we can set the permissions for each layer directory individually.

To remove a share we use following request:

"method": "DELETE",
"headers": [
  "OCS-APIRequest": true
],
"scheme":	"https",
"host": "cloud.permaplant.net",
"filename": "/ocs/v2.php/apps/files_sharing/api/v1/shares/<share_id>"

And to update a share we use:

"method": "PUT",
"headers": [
  "OCS-APIRequest": true
],
"body": {
  "permissions": 1
},
"scheme":	"https",
"host": "cloud.permaplant.net",
"filename": "/ocs/v2.php/apps/files_sharing/api/v1/shares/<share_id>"

Note that we can only update one value at a time with the PUT request.

React Components

There are a number of components which help with interacting with Nextcloud files.

Image Components

There are four components that handle fetching and displaying images from Nextcloud.

NextcloudImage: This component fetches an image from the user directory in Nextcloud and renders it.
PublicNextcloudImage: This component fetches and renders an image from a public share.
NextcloudKonvaImage: This component fetches an image from the user directory in Nextcloud and creates a shape for Konva (Canvas library used in PermplanT).
PublicNextcloudKonvaImage: This component fetches an image from the Nextcloud public share and creates a shape for Konva.

File Selection

Component which shows the content of a Nextcloud directory and lets the user choose a file.

Will be implemented in #475.

https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/comments.html
https://docs.oracle.com/cd/E12839_01/portal.1111/e10235/webdav007.htm#POUSR1607
https://docs.nextcloud.com/server/25/user_manual/en/files/access_webdav.html#
http://www.webdav.org/specs/rfc4918.html

Limitations

"CORS is an HTTP-header based mechanism that allows a server to indicate any origins (domain, scheme, or port) other than its own from which a browser should permit loading resources." -- Mozilla MDN

Nextcloud offers no options to change the CORS configuration. This means that all requests coming from a different origin than the one Nextcloud is hosted on are blocked.

The PermaplanT production environment has following structure:

Frontend: "https://www.permaplant.net".
Backend: "https://www.permaplant.net/api"
Nextcloud: "https://cloud.permaplant.net"
Keycloak: "https://auth.permaplant.net/realms/PermaplanT"

This means the origin for Nextcloud differs from the origin of the PermaplanT frontend. Consequently CORS has to be configured to allow requests from the frontend origin otherwise the requests to Nextcloud are blocked by the browser. To circumvent the restrictions or the lack of configuration options by Nextcloud we implemented a proxy in front of the Nextcloud instance which sets the needed headers for the OPTIONS preflight which is performed by the browser.

Research about other Nextcloud Features

calendar

Nextcloud Calendar App is a frontend for the Nextcloud CalDAV backend.

resources

CalDavBackend implementation
CalDAV

Contacts

Contacts are stored in vCards and can be managed with CardDAV. nextcloud/contacts is based on sabredav(most popular WebDAV framework for PHP) nextcloud/contacts implements CardDAV:

"vCard Extensions to WebDAV (CardDAV) is an address book client/server protocol designed to allow users to access and share contact data on a server. CardDAV is based on WebDAV, which is based on HTTP, and it uses vCard for contact data.(2)" wikipedia

https://apps.nextcloud.com/apps/contacts
github repository
https://github.com/nextcloud/contacts/blob/main/lib/Dav/PatchPlugin.php
CardDAV clients
CardDAV libraries

Groups

Groups are part of the user management and not to be confused with circles. While circles offer similar functionality, they are more versatile and can be created by all users while groups can only be created by admins.

Circles API

API test with curl (USERNAME, PSWD and BASE_URL have to be set):

curl -u USERNAME:PSWD -X GET 'https://BASE_URL/nextcloud/ocs/v2.php/apps/circles/circles' -H "OCS-APIRequest: true"

This returns a list of circles visible to the authenticated user.

Working API calls (tested with NC version 25.0.4-1~deb11):

add member

curl -u USERNAME:PSWD -X POST 'https://BASE_URL/nextcloud/ocs/v2.php/apps/circles/circles/CIRCLE_ID/members/multi' -H "OCS-APIRequest: true" -H "Content-Type: application/json" -d '{"members":[{"id":"USER_ID","type":1}]}'

create circle

curl -u USERNAME:PSWD -X POST 'https://BASE_URL/nextcloud/ocs/v2.php/apps/circles/circles' -H "OCS-APIRequest: true" -H "Content-Type: application/json" -d '{"name":"test_circle_3","personal":false,"local":false}'

delete member from circle

curl -u USERNAME:PSWD -X DELETE 'https://BASE_URL/nextcloud/ocs/v2.php/apps/circles/circles/CIRCLE_ID/members/MEMBER_ID' -H "OCS-APIRequest: true"

get circles

curl -u USERNAME:PSWD -X GET 'https://BASE_URL/nextcloud/ocs/v2.php/apps/circles/circles' -H "OCS-APIRequest: true"

get members

curl -u USERNAME:PSWD -X GET 'https://BASE_URL/nextcloud/ocs/v2.php/apps/circles/circles/CIRCLE_ID/members' -H "OCS-APIRequest: true"

resources

https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/occ_command.html#http-user-label
https://github.com/nextcloud/circles
Circle routes

Maps

The maps Nextcloud plugin offers a REST API. The documentation can be found here.

The GET endpoint /favorite was tested with curl and basic authentication:

curl -u USERNAME:PSWD -X GET 'https://BASE_URL/nextcloud/index.php/apps/maps/api/1.0/favorites'

Chat

sending a message:

// sends once, Err if it does not work on network or nextcloud level
fn send_message (
	&self,
	message: String,
	chat: String,
) -> Result<reqwest::Response, reqwest::Error> {
	let mut headers = header::HeaderMap::new();
	headers.insert("Content-Type", "application/json".parse().unwrap());
	headers.insert("Accept", "application/json".parse().unwrap());
	headers.insert("OCS-APIRequest", "true".parse().unwrap());

	let result = reqwest::Client::new()
		.post(&format!(
			"{}/ocs/v2.php/apps/spreed/api/v1/chat/{}",
			&self.url, chat
		))
		.basic_auth(&self.user, self.pass.as_ref())
		.headers(headers)
		.body(format!(
			"{{\"token\": \"{}\", \"message\": \"{}\"}}",
			chat, message
		))
		.send();
	match result {
		Ok(response) => match response.error_for_status() {
			Ok(response) => Ok(response),
			Err(error) => Err(error),
		},
		Err(error) => Err(error),
	}
}

or via CURL:

curl -sS -d "{\"token\": \"$CHAT\", \"message\": \"$*\"}" -H "Content-Type: application/json" -H "Accept: application/json" -H "OCS-APIRequest: true" -u "user:password" https://nextcloud.markus-raab.org/nextcloud/ocs/v2.php/apps/spreed/api/v1/chat/$CHAT

Setup scripts for PermaplanT

The setup guide for the whole backend can be found in backend

keycloak

This setup uses the keycloak image packaged by bitnami. More information can be found here

settings:

admin user: admin
admin password: admin

Start a keycloak instance with a persistent storage with:

docker compose up

Open http://localhost:8081/admin.
Sign in with user admin and password admin.
Click on master -> Create Realm.
Name the realm PermaplanT and click Create.

Either import the frontend client configuration:

Click on Clients -> Import client.
Click Browse Select /doc/setups/keycloak/PermaplanT.json Click Save

or manually create the client:

Click on Clients -> Create client.
Set the Client ID to PermaplanT. Click Next two times.
Set values: Root URL = http://localhost:5173, Valid redirect URIs = /*, Web origins = +.
Click Save.

Create a second client swagger-ui with Root URL = http://localhost:8080/doc/api/swagger/ui (everything else the same as above).

Go to Users and create a user test.
Click Credentials and set password to test.

nextcloud

Docker compose setup for nextcloud with mariadb:

Start the Nextcloud instance with:

docker compose up

nginx (WIP)

This setup should spin up a Nextcloud instance behind a nginx reverse proxy with TLS enabled. Https is required for Nextcloud to allow the login via Keycloak.

Although everything seems to work correctly the login with Keycloak fails anyways...

This means requests against the Nextcloud APIs have to be tested with a remote Nextcloud instance.

Local Keycloak Setup

Start Keycloak

Via docker run:

docker run -p 8081:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:21.1.1 start-dev

or use the docker-compose.yml to start keycloak with persistent storage via

docker compose up

more about the docker compose setup can be found in /doc/setups/README.md

Setup Keycloak:

Open http://localhost:8081/admin.
Sign in with user admin and password admin.
Click on master -> Create Realm.
Name the realm PermaplanT and click Create.

Create a second client swagger-ui with Root URL = http://localhost:8080/doc/api/swagger/ui (everything else the same as above).

Go to Users and create a user test.
Click Credentials and set password to test.

Nextcloud Setup

You can use the docker-compose.yml in this folder to start a local Nextcloud instance.

Required Plugins

The PermaplanT app requires to have following plugins installed in Nextcloud:

user_oidc This plugin allows to configure OpenID Connect providers for authentication

create cert for PermaplanT following this guide: https://gist.github.com/dahlsailrunner/679e6dec5fd769f30bce90447ae80081

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout my-site.key -out my-site.crt -config my-site.conf -passin pass:YourStrongPassword

create a pfx file

sudo openssl pkcs12 -export -out permaplant.pfx -inkey permaplant.key -in permaplant.crt

import pfx file in browser

Postgis Docker

Instead of setting up psql server on your local machine, you could use a 'postgis' Docker container as another option.

hub.docker postgis image

Use docker-compose.yml in /doc/setups/postgis with the following command to start the container.

docker-compose up -d

It's worth noting that the PostGIS Docker image makes the permaplant user a 'superuser'.

Now, carry out the migration as you usually do.

If you want to use the psql CLI, use following command.

docker exec -ti postgis psql -U permaplant

Testing Strategy

Testing Approach

The software testing strategy aims to ensure the delivery of high-quality software by employing a comprehensive testing approach throughout the development lifecycle. This strategy combines various testing types and levels to validate the functionality, performance, and security of the software.

The testing approach for PermaplanT will follow a mix of unit testing, integration testing, and system testing. Unit testing will be conducted for individual components and functions to ensure that they are working as expected. Integration testing will be conducted for API endpoints and interactions between components to ensure that they are functioning correctly together. System tests will be conducted as manual tests and automated e2e tests.

Objectives

Ensure that the software meets functional requirements and operates as intended.
Identify and mitigate risks associated with software defects and failures.
Enhance user experience by maintaining low bugrate and responsiveness.
Improve overall software quality and reliability.
Maintain an 80% backend branch coverage.

Out of Scope:

Database tests
Stress tests

In Scope:

End-to-End testing of important use cases
Integration testing of various modules and components
System tests
Performance tests
Security tests
Regression testing
User acceptance testing
Compatibility testing on different platforms, browsers, and devices

Testing Types and Levels

1. Unit Testing

Unit tests are used to test individual units of code in isolation from the rest of the system. This is important because it allows us to validate that each unit is working as intended, without interference from other parts of the system.

Unit tests must be created by every developer during the development process, following the Arrange-Act-Assert (AAA) pattern.

Short example:

#![allow(unused)]
fn main() {
struct Plants;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_abs_for_a_negative_number() {
    // Arrange
    let negative = -5;

    // Act
    let answer = abs(negative);

    // Assert
    assert_eq!(answer, 5);
    }
}
}

Frontend

For the frontend unit tests will be used to test the following areas:

State management logic: Since the frontend relies heavily on state management, it is important to ensure that the state is being properly managed and updated.
Functions that handle data manipulation, such as sorting or filtering
Components that render UI elements
Correct event handling
Form validation and submission

Backend

For the backend, unit tests will be used to test the following areas:

Database queries and operations
Business logic and data manipulation, e.g. code that performs calculations, manipulates data, or makes decisions based on input
Authentication and authorization
Error handling

In the backend unit tests can be found in the src/test directory.

2. Integration Testing

Integration tests are used to test the integration between different parts of the system. This is important because it allows us to validate that the different parts of the system are working together correctly.

In the application the integration tests will be used to test the following areas:

Continuous Integration (CI) pipelines must run integration tests for different modules and components.

Frontend

API calls using a mock API

Backend

API endpoints
Database queries

In the backend integration tests can be found in the src/test/ directory. The whole module is annotated with #[cfg(test)] and will therefore only be compiled for tests.

3. System Testing

System testing will include end-to-end testing of the application to ensure overall functionality and user experience. This will include testing of all features, navigation, and error handling.

System test scenarios must be derived from the use cases and the requirements they imply.
Manual system tests are documented in doc/tests/manual/protocol.md.
Automated system tests (e2e tests) can be found in the top-level e2e folder.
Both are specified in Gherkin syntax.
Exploratory testing techniques must be utilized to uncover potential issues and edge cases.

4. Performance Testing

TBD by @badnames

5. Security Testing

TBD by @temmey

Test Environment and Infrastructure

Test environments must mirror production environments as closely as possible.
Virtualization and containerization technologies, such as Docker must be utilized for test environment management.
Test environments must be version controlled and easily reproducible.

Testing Tools

E2E: Python Playwright & Pytest + plugins
Backend: Rust built-in tests by cargo
Frontend: Vitest

Test Data Management

Test data must be synthetic.
Test data must cover a variety of scenarios, including at least valid and invalid cases.
Equivalence partitioning and boundary value analysis tests should be done when it makes sense.

Test Execution and Reporting

Test cases must be executed manually or automated, as appropriate for each testing type.
All automated tests must be executed by CI.
Integration tests must be executed by the CI pipeline on every push to PR and every merge to master.
Test metrics, such as test coverage and test execution time, must be tracked in the pipeline.
System tests and User acceptance tests must be performed before every release.
Manual tests will be documented under doc/tests/manual/reports
An Email is send whenever master fails, with a small report containing information since last build.

Test Automation

Unit and Integration tests must be fully automated.
Security and Performance tests may be manual.
System tests are automated (if possible) according to the e2e guidelines.

Other Considerations

Tests should be run before committing via pre-commit hooks
Tests should be run on different configurations (e.g. production, staging)

Backend Testing

Auth

As Actix is validating tokens in integration tests you need to send authenticated requests.
To do that use the token provided by the function init_test_app and insert it into the Authorization header.

There is no need for an authorization server during tests.
The token will be created using a jwk that was specifically created for tests. The same jwk will be used to validate the tokens.

Frontend testing

Libraries

PermaplanT uses the Vitest testing framework.

React Test Renderer, React Testing Library and User Event are available as companion libraries.

Types and organization of tests

We distinguish three different kinds of tests in the frontend of PermaplanT.

Render tests
DOM tests
Logic tests

Each of these test-types may be used for unit testing or integration testing.

All tests related to a component can be found under the same directory in <component name>.test.tsx

Render tests

Render tests make use of React Test Renderer to check if a components layout has unexpectedly changed by transforming it to plain html. Since most components are made up of other sub-components, most tests of this kind are considered to be integration tests.

After a new render test is run for the first time, React Test Renderer will record a snapshot of the selected component and store it in the __snapshots__ subfolder. If the same component renders differently in the future, e.g. because a subcomponent was changed, the test will fail.

To fix the issue, the programmer has to decide if the changes are intentional and then either fix the issue, or regenerate the affected snapshots using:

npm run test -- --updateSnapshot

DOM tests

DOM tests are used to test a components response to user interaction. In the current test setup this is accomplished using a simulated DOM provided by React Testing Library and js-dom. This makes it possible to run these tests even when a browser is not available (e.g. as part of the CI-pipeline).

If possible, User Event should be used to mock user input.

Logic Tests

The remaining tests are used to test our helper functions and in general code that is not tied to the DOM.

Vitest provides plenty of APIs that can be used to mock functions for this purpose.

Mocking API requests should be done with MSW. There is an example of this in src/__test_utils__/msw_handlers/plants.ts. The gist is, MSW intercepts all requests, for which a handler is defined returns the handler's response instead of the backend's.

Testing strategy

Frontend tests should generally follow these principles:

Concentrate on writing meaningful tests instead of increasing code coverage for the sake of increasing code coverage.
After fixing a bug, add regression tests wherever possible.
Focus on testing code that is hard to verify using E2E or manual testing.
DOM and Snapshot tests have low priority. They are a nice tool to detect unexpected changes while restyling or reorganizing components, but provide little utility otherwise.

In practice this means that most "CRUD" style components will usually require little to no frontend tests whatsoever. The main utility of frontend tests is to ensure that more complex algorithms and calculations such as those in frontend/features/map_planning/layers/utils/PolygonUtils.ts are implemented correctly. Furthermore, frontend tests are handy to ensure that PermaplanTs state management system is updated as expected. Of course there are plenty more use cases for frontend testing, but the ones presented above should give a general idea.

Optimizing code for testability

Avoid side effects as much as possible. It is generally easiest to test pure functions (i.e. functions without side effects).

Separating UI code (React Components) from code that performs other tasks - such as state mutation - facilitates testing immensely.

Performance tests

Frontend performance must always be viewed from a user centered perspective. To avoid premature optimization always keep in mind that our main target is to ensure that a majority of users don't experience noticeable slowdowns on our targeted hardware during average use cases.

Manual testing as well as user testing is therefore the best strategy for detecting the most relevant performance issues. Automated performance testing, e.g. using Google Lighthouse, should only be used to avoid sudden, unexpected performance degradations or to monitor long term performance trends. Under no circumstances should any performance metric be used as a target.

Manual Test Protocol

Plant Search

Description: Show a selection of plants if the search input is empty.
Given I am on a map page with the plant layer active
When I have an empty search box
Then I can see various plants as results
Actual Result:
Test Result:
Notes:

Heatmap

Description: Test whether the heatmap endpoints generates the image correctly.
Given I am on a map page with the plant layer active
When I start planting a plant
Then I see suitable places for that plant
Actual Result:
Test Result:
Notes:

Layer opacity

Description: Check whether the opacity of a layer changes.
Given I am on a map page with a base layer image configured
When dragging the slider for the base layer in the layer section of the toolbar to 50%
Then I can see the change in opacity of the base layer image
When I change the size of the toolbar
Then I can see the slider and the filling change in size proportionally. Therefore 50% of the slider should be filled.
Actual Result:
Test Result:
Notes:

Base Layer

Description: Check whether the maps background image is displayed correctly.
Given I am on a map page with the base layer active
When I select a base layer image
Then I can see the base layer image on the canvas
Actual Result:
Test Result:
Notes:

Base Layer: move image

Description: Check whether the maps background image is displayed correctly.
Given I am on a map page with the base layer active
When I select a base layer image
When I increase the base layers x position
Then I can see the base layer image is moved to the right
Actual Result:
Test Result:
Notes:

Grid

Description: Display a point grid on the screen.
Given I am on a map page
When I Zoom in or out
Then the grid spacing is changing
Actual Result:
Test Result:
Notes:

Map Editor Guided Tour

Description: Check whether the Guided Tour leaves the Map Editor in its original state.
Given I am on a map page
When I do the Guided Tour
Then after I have done the Guided Tour the map is the same as before
Actual Result:
Test Result:
Notes: Check if all actions can be done as described.

Additional name on map: plant labels

Description: Test additional names being displayed properly.
Given I am on the map page with the plants layer active
When I create a new plant from the inventory.
Then I can see the additional name on the label when hovering over the plant.
Actual Result:
Test Result:
Notes: The additional name must also be visible when a different account views the same map in parallel.

Description: Test additional names being displayed properly.
Given I am on the map page with the plants layer active
When I create a new plant from the inventory.
When I click on the new plant icon.
Then I can see the additional name in the left toolbars heading.
Actual Result:
Test Result:
Notes: The additional name must also be visible when a different account views the same map in parallel.

Additional name on map: updates

Description: Test additional names being displayed properly.
Given I am on the map page with the plants layer active
When I create a new plant from the inventory.
When I go to the inventory page and change the seeds name.
Then I can see the changes in the plant label and left toolbar.
Actual Result:
Test Result:
Notes: The additional name must also be visible when a different account views the same map.

Layer Management: Initial Order of Layers

Description: Test initial order of layers
When I create a new map
Then Base Layer is at bottom of layer list and Plant Layer is on top of layer list
Actual Result:
Test Result:
Notes:

Layer Management: Correct konva rendering of layer order on new map

Description: Test correct rendering order of konva layers.
Given I am on a new map
When I add a background image in Base Layer
When I add an overlapping rectangle in Drawing Layer
When I add an overlapping plant in plant layer
Then Plant in is front of rectangle and rectangle is in front of background image
Actual Result:
Test Result:
Notes:

Layer Management: Renaming of layer

Description: Test if Drawing Layer can be renamed.
Given I am on a new map
When I rename the Drawing Layer
Then The new name is visible in the layer list
Actual Result:
Test Result:
Notes:

Layer Management: Creation of new layer

Description: Test if new layer can be created.
Given I am on a new map
When I select a layer and create a new one
Then The new layer is visible above currently selected layer
Actual Result:
Test Result:
Notes:

Layer Management: Change order of layers

Description: Test if the order of layers can be updated correctly.
Given I am on a map with 2 drawing layers with overlapping rectangles
When I select the upper Drawing Layer and move it below the other one
Then The order in the layer list is updated and the rectangle of the new upper drawing layer is shown in front of the lower one on the map.
Actual Result:
Test Result:
Notes:

Layer Management: Delete Drawing Layer

Description: Test if Drawing Layer can be deleted
Given I am on a map with some drawing on a Drawing Layer.
When I delete the Drawing Layer
Then The layer disappears from layer list and drawings are deleted from map
Actual Result:
Test Result:
Notes:

Layer Management: Deletion of Plant Layer not possible

Description: Test if deletion of Plant layer is disabled
Given I am on a new map.
When I select the Plant Layer
Then Button to delete layer is disabled
Actual Result:
Test Result:
Notes:

Layer Management: Deletion of Base Layer not possible

Description: Test if Deletion of Base layer is disabled
Given I am on a new map.
When I select the Base Layer
Then Button to delete layer is disabled
Actual Result:
Test Result:
Notes: The additional name must also be visible when a different account views the same map.

Layer Management: Initial Order of Layers

Description: Test initial order of layers
When I create a new map
Then Base Layer is at bottom of layer list and Plant Layer is on top of layer list
Actual Result:
Test Result:
Notes:

Layer Management: Correct konva rendering of layer order on new map

Description: Test correct rendering order of konva layers.
Given I am on a new map
When I add a background image in Base Layer
When I add a rectangle in Drawing Layer
When I add a plant in plant layer
Then Plant in is front of rectangle and rectangle is in front of background image
Actual Result:
Test Result:
Notes:

Layer Management: Renaming of layer

Description: Test if Drawing Layer can be renamed.
Given I am on a new map
When I rename the Drawing Layer
Then The new name is visible in the layer list
Actual Result:
Test Result:
Notes:

Layer Management: Creation of new layer

Description: Test if new layer can be created.
Given I am on a new map
When I select a layer and create a new one
Then The new layer is visible above currently selected layer
Actual Result:
Test Result:
Notes:

Layer Management: Change order of layers

Description: Test if the order of layers can be updated correctly.
Given I am on a map with 2 drawing layers with overlapping rectangles
When I select the upper Drawing Layer and move it below the other one
Then The order in the layer list is updated and the rectangle of the new upper drawing layer is shown in front of the lower one on the map.
Actual Result:
Test Result:
Notes:

Layer Management: Delete Drawing Layer

Description: Test if Drawing Layer can be deleted
Given I am on a map with some drawing on a Drawing Layer.
When I delete the Drawing Layer
Then The layer disappears from layer list and drawings are deleted from map
Actual Result:
Test Result:
Notes:

Layer Management: Deletion of Plant Layer not possible

Description: Test if deletion of Plant layer is disabled
Given I am on a new map.
When I select the Plant Layer
Then Button to delete layer is disabled
Actual Result:
Test Result:
Notes:

Layer Management: Deletion of Base Layer not possible

Description: Test if Deletion of Base layer is disabled
Given I am on a new map.
When I select the Base Layer
Then Button to delete layer is disabled
Actual Result:
Test Result:
Notes:

Layer Management: Undo deletion

Description: Test if deleted layer can be restored
Given I am on a map with some drawing on a drawing layer.
When I delete the drawing layer
Then Layer disappears from layer list and drawings are deleted from map
When I press undo
Then Layer appears again at same position as it was before deletion and drawings are visible again.
Actual Result:
Test Result:
Notes:

Layer Management: Top layer cannot be moved up

Description: Test if the top layer cannot be moved up
Given I am on a new map.
When I select the top layer.
Then Button to to move layer up is disabled
Actual Result:
Test Result:
Notes:

Layer Management: Bottom layer cannot be moved down

Description: Test if the bottom layer cannot be moved down
Given I am on a new map.
When I select the bottom layer.
Then Button to to move layer down is disabled
Actual Result:
Test Result:
Notes:

Layer Management: Renaming of Plant Layer not possible

Description: Test if Renaming of Plant layer is not possible
Given I am on a new map.
When I select the Plant Layer
Then Button to rename layer is disabled
Actual Result:
Test Result:
Notes:

Layer Management: Renaming of Base Layer not possible

Description: Test if Renaming of Base layer is not possible
Given I am on a new map.
When I select the Base Layer
Then Button to rename layer is disabled
Actual Result:
Test Result:
Notes:

Shade layer: add shading

Description: Add a new Shading to the map.
Given I am on the map page with the shade layer active
When I click on the 'Light' button
When I click on the map
Then I can see that a new shading was added
Actual Result:
Test Result:
Notes: Repeat this test for all Shading types

Shade layer: remove shading

Description: Remove a Shading from the map.
Given I am on the map page with the shade layer active and a Shading is selected
When I click on 'Delte' in the left toolbar
Then I can see that a new shading was deleted
Actual Result:
Test Result:

Shade layer: edit shade type

Description: Change the shade of a shading.
Given I am on the map page with the shade layer active and a Shading is selected
When I select different shade from the drop-down menu in the left toolbar
Then I can see that the shade is changed successfully
Actual Result:
Test Result:
Notes: select each shading type at least once

Shade layer: set creation date in the future

Description: Update the date from which the shading should be active
Given I am on the map page with the shade layer active and a Shading is selected
When I select the current date in the timeline
When I select a creation date in the future
Then I can see that the shading is no longer shown on the map
Actual Result:
Test Result:

Measurement: Measure a distance

Description: Test whether distance can be measured successfully
Given I am on a map page
When I click on the measurement button
When I measure a distance
Then I see a measurement line
Then I see the measured distance
Actual Result:
Test Result:
Notes:

Measurement: Cancel measurement without deleting measurements

Description: Verify that measured distances don't disappear when the measurement mode is canceled using the button in the status panel.
Given I am on a map page
When I click on the measurement button
When I measure a distance
When I cancel the measurement mode using the status panel
Then the measurement layer is no longer active
Then I can still see the measured distance
Actual Result:
Test Result:
Notes:

Measurement: Cancel measurement and delete all measurement lines

Description: Verify that measured distances disappear when the measurement mode is canceled using the measurement button.
Given I am on a map page
When I click on the measurement button
When I measure a distance
When I cancel the measurement mode using the measurement button in the toolbar
Then I can no longer see the measured distance
Actual Result:
Test Result:
Notes:

Measurement: Delete measurements after measurement mode is deactivated

Description: Verify that measured distances don't disappear when the measurement mode is canceled using the button in the status panel.
Given I am on a map page
When I click on the measurement button
When I measure a distance
When I cancel the measurement mode using the status panel
When I click on the measurement button
Then I can no longer see the measured distance
Actual Result:
Test Result:
Notes:

Map Overview: More than 30 Layers should be visible

Description: Test that pagination works on the map overview screen
Given I am on the map overview screen
When I create more than 30 maps
Then I can see all maps after scrolling to the bottom of the page.
Actual Result:
Test Result:
Notes:

Measurement: Measure a distance

Description: Test whether distance can be measured successfully
Given I am on a map page
When I click on the measurement button
When I measure a distance
Then I see a measurement line
Then I see the measured distance
Actual Result:
Test Result:
Notes:

Measurement: Cancel measurement without deleting measurements

Description: Verify that measured distances don't disappear when the measurement mode is canceled using the button in the status panel.
Given I am on a map page
When I click on the measurement button
When I measure a distance
When I cancel the measurement mode using the status panel
Then the measurement layer is no longer active
Then I can still see the measured distance
Actual Result:
Test Result:
Notes:

Measurement: Cancel measurement and delete all measurement lines

Description: Verify that measured distances disappear when the measurement mode is canceled using the measurement button.
Given I am on a map page
When I click on the measurement button
When I measure a distance
When I cancel the measurement mode using the measurement button in the toolbar
Then I can no longer see the measured distance
Actual Result:
Test Result:
Notes:

Measurement: Delete measurements after measurement mode is deactivated

Description: Verify that measured distances don't disappear when the measurement mode is canceled using the button in the status panel.
Given I am on a map page
When I click on the measurement button
When I measure a distance
When I cancel the measurement mode using the status panel
When I click on the measurement button
Then I can no longer see the measured distance
Actual Result:
Test Result:
Notes:

Shade layer: set removal date in the future

Description: Update the date from which the shading should be active
Given I am on the map page with the shade layer active and a Shading is selected
When I select the current date in the timeline
When I select a creation date in the past
When I select a removal date in the future
Then I can see that the shading is shown on the map
Actual Result:
Test Result:

Shade layer: set removal date in the past

Description: Update the date until which the shading should be active
Given I am on the map page with the shade layer active and a Shading is selected
When I select the current date in the timeline
When I select a creation date in the past
When I select a removal date in the past after the creation date
Then I can see that the shading is no longer shown on the map
Actual Result:
Test Result:

Shade layer: add polygon point

Description: Edit the polygon of a shading
Given I am on the map page with the shade layer active and a Shading is selected
When I press the pencil button in the left toolbar
Then I can see that a message describing the selected action is shown in the status bar
Then I can see that a highlighted border is drawn around the polygon
When I click anywhere on the map
Then I can see that a point has been added to the nearest polygon edge
Actual Result:
Test Result:

Shade layer: remove polygon point

Description: Edit the polygon of a shading
Given I am on the map page with the shade layer active and a Shading is selected
When I press the eraser button in the left toolbar
Then I can see that a message describing the selected action is shown in the status bar
Then I can see that a highlighted border is drawn around the polygon
When I click on a polygon point
Then I can see that the point has been removed from the polygon
Actual Result:
Test Result:

Shade layer: move polygon point

Description: Edit the polygon of a shading
Given I am on the map page with the shade layer active and a Shading is selected
When I press the cursor button in the left toolbar
Then I can see that a message describing the selected action is shown in the status bar
Then I can see that a highlighted border is drawn around the polygon
When I drag and release a polygon point
Then I can see that the point is now at a new position
Actual Result:
Test Result:
Notes:

Map Search

Description: Appropriate maps should be displayed for each search term
Given I am on a map overview page
When I search for as map using the search field
Then the maps are filtered appropriately
Actual Result:
Test Result:
Notes:

Map Deletion

Description: A map should no longer be available after it has been deleted.
Given I am on a map overview page
When I delete a map
Then the map is no longer available in the overview
Actual Result:
Test Result:
Notes:

Heatmap: Plant layer should be above heatmap

Description: Verify that the PLant Layer is above the Heatmap Layer
Given I am on a map page
When I place some tomatoes on the map
When I select a potato and try to place it near the tomatoes so that heatmap is shown
Then I can see that the heatmap is below the plants
Actual Result:
Test Result:
Notes:

Heatmap: Change position of plant layer

Description: Verify that the heatmap changes its position when the plant layer is moved in priority
Given I am on a map page where plant layer is above an drawing layer
When I place some tomatoes on the plant layer
When I draw a filled rectangle on the drawing layer so that it overlaps with the tomatoes
When I select a potato and try to place it near the tomatoes so that heatmap is shown
Then I can see that the heatmap is below the plants and above the rectangle
When I move the plant layer below the drawing layer
Then I can see that the heatmap is below the rectangle and below the plants
Actual Result:
Test Result:
Notes:

Report

A report is the execution of one test protocol. It contains a report header at the beginning. A report can chose to perform a subset of the test cases from the protocol, but should mention that some tests are skipped.

Naming convention

The report should be named after todays date in this format YYMMDD.

Heatmap with Shade

General

Tester: Gabriel
Date/Time: 31.07.2023 21:50
Duration: 15 min
Commit/Tag: a8b0079cbdd638aea5600373434d8dddcca8e7e7
Planned tests: 1
Executed tests: 1
Passed tests: 1
Failed tests: 0

Error Analysis

Closing remarks

This test was executed to show how the heatmap can be generated without the frontend being fully implemented.

Testcases

TC-007 - Heatmap

Get a clean database with all migrations: cd backend && diesel database reset.
Insert the plants and relations using the scraper (cd scraper && npm run insert)
Start the backend (cd backend && cargo run).
Create a map (via Postman, equivalent cURL below - remember to insert the token).

curl --location 'http://localhost:8080/api/maps' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Test1",
    "creation_date": "2023-07-06",
    "is_inactive": false,
    "zoom_factor": 100,
    "honors": 0,
    "visits": 0,
    "harvested": 0,
    "privacy": "public",
    "description": "",
    "geometry": {
        "rings": [
            [
                {
                    "x": 0.0,
                    "y": 0.0
                },
                {
                    "x": 100.0,
                    "y": 0.0
                },
                {
                    "x": 100.0,
                    "y": 100.0
                },
                {
                    "x": 50.0,
                    "y": 100.0
                },
                {
                    "x": 50.0,
                    "y": 50.0
                },
                {
                    "x": 0.0,
                    "y": 50.0
                },
                {
                    "x": 0.0,
                    "y": 0.0
                }
            ]
        ],
        "srid": 4326
    }
}'

The result should be:

{
  "id": 1,
  "name": "Test1",
  "creation_date": "2023-07-06",
  "deletion_date": null,
  "last_visit": null,
  "is_inactive": false,
  "zoom_factor": 100,
  "honors": 0,
  "visits": 0,
  "harvested": 0,
  "privacy": "public",
  "description": "",
  "location": null,
  "owner_id": "361c7c28-020f-4b31-84ea-cc629cc43180",
  "geometry": {
    "rings": [
      [
        {
          "x": 0.0,
          "y": 0.0,
          "srid": 4326
        },
        {
          "x": 100.0,
          "y": 0.0,
          "srid": 4326
        },
        {
          "x": 100.0,
          "y": 100.0,
          "srid": 4326
        },
        {
          "x": 50.0,
          "y": 100.0,
          "srid": 4326
        },
        {
          "x": 50.0,
          "y": 50.0,
          "srid": 4326
        },
        {
          "x": 0.0,
          "y": 50.0,
          "srid": 4326
        },
        {
          "x": 0.0,
          "y": 0.0,
          "srid": 4326
        }
      ]
    ],
    "srid": 4326
  }
}

Create a shading.

curl --location 'http://localhost:8080/api/maps/1/layers/shade/shadings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "layerId": 3,
    "shade": "light shade",
    "geometry": {
        "rings": [
            [
                {
                    "x": 0.0,
                    "y": 0.0
                },
                {
                    "x": 20.0,
                    "y": 0.0
                },
                {
                    "x": 20.0,
                    "y": 20.0
                },
                {
                    "x": 0.0,
                    "y": 20.0
                },
                {
                    "x": 0.0,
                    "y": 0.0
                }
            ]
        ],
        "srid": 4326
    },
    "actionId": "00000000-0000-0000-0000-000000000000"
}'

The result should be:

{
  "id": "21c9ca45-5ff4-492a-a537-7eb64c134613",
  "layerId": 3,
  "shade": "light shade",
  "geometry": {
    "rings": [
      [
        {
          "x": 0.0,
          "y": 0.0,
          "srid": 4326
        },
        {
          "x": 20.0,
          "y": 0.0,
          "srid": 4326
        },
        {
          "x": 20.0,
          "y": 20.0,
          "srid": 4326
        },
        {
          "x": 0.0,
          "y": 20.0,
          "srid": 4326
        },
        {
          "x": 0.0,
          "y": 0.0,
          "srid": 4326
        }
      ]
    ],
    "srid": 4326
  },
  "addDate": null,
  "removeDate": null
}

Execute the request.

curl -o file.png --location 'http://localhost:8080/api/maps/1/layers/plants/heatmap?plant_id=1&plant_layer_id=2&shade_layer_id=3' \
--header 'Authorization: Bearer <token>'

Verify:

The bottom left corner should be transparent, everything else should be green.
The top left corner should be green (as there is shade there and plant with id 1 likes shade); the rest should be yellow.

Manual Test Report (pre v0.3 case study release)

General

Tester: Aydan Namdar Ghazani
Date/Time: 25 July 2023
Duration: 15 minutes
Commit/Tag: af6b307
Setup: local build
Planned tests: 14
Executed tests: 14
✔️Passed tests: 10
⚠️Problematic tests: 3
❌Failed tests: 1

Error Analysis

TC-007: Functional deviation or limitation.
TC-009: The test case worked, just the image loading error appeared.
TC-010: Same as 009.
TC-013: Functional deviation or limitation. Priority: TBD.

Closing remarks

How is the current state of the software?

The software seems to be a in a reasonable state with almost all core functionalities working.

Only the timeline had some slight issues and one bug (issue #699) seemed to be present on the map creating page.

Have the quality objectives been achieved?

There were no defined quality objectives at this time.

What are the consequences drawn from the current state, including: how can future errors be avoided, how can the development process be improved?

It worked quite well! More tests could be automated to decrease manual effort for testing.

Testcases

Description: Successfully login to PermaplanT
Preconditions:
Test Steps:
1. Press the login button on the navbar.
2. Enter credentials.
3. Press Login.
Expected Result:
- Get redirected to the homepage.
- Be logged in.
- See a Hello message pop up.
Actual Result:
Test Result: ✔️
Notes:

TC-002 - Translation

Description: Switch language on website
Preconditions:
Test Steps:
1. Change the language in the navbar
Expected Result:
- Language should be changed after selecting a new one.
Actual Result:
Test Result: ✔️
Notes:

TC-003 - Use Case: Map Creation

Description: Successfully create a new map.
Preconditions:
- Be logged in.
Test Steps:
1. Go to the map editor page.
2. Create a new map.
3. Enter valid stuff.
Expected Result:
- Map should be successfully created.
Actual Result:
Test Result: ✔️
Notes:

TC-004 - Map Creation (Negative)

Description: Can't create a map with a name that exists
Preconditions:
- Be logged in.
Test Steps:
1. Go to the map editor page.
2. Create a map with a name that already exists.
3. Enter valid stuff.
Expected Result:
- Map should not be created.
- Error message pops up on the top right.
Actual Result:
Test Result: ✔️
Notes:

TC-005 - Plant Search

Description: Show a selection of plants if the search input is empty.
Preconditions:
- No search input has been provided in the plant search.
Test Steps:
1. Naviagate to the map page.
2. Select a map.
3. Select the plant layer in the right map menu.
4. Push the search icon in the lower right menu.
Expected Result:
- A selection of plants is shown to the user.
Actual Result:
Test Result: ✔️
Notes:

TC-006 - Plant Search

Description: Return expected results for a given search in the selected language.
Preconditions:
- The search term "tomato" has been typed into the search field.
Test Steps:
1. Naviagate to the map page.
2. Select a map.
3. Select the plant layer in the right map menu.
4. Push the search icon in the lower right menu.
5. Write "tomato" into the search field.
Expected Result:
- The plants shown contain the string "tomato" in part of the datacolumns as outlined in the usecase document.
Actual Result:
Test Result: ✔️
Notes:

TC-007 - Plant Search

Description: Returns results for searches in the language that was not selected.
Preconditions:
- The search term "fichte" has been typed into the search field.
Test Steps:
1. Navigate to the map page.
2. Select a map.
3. Select the plant layer in the right map menu.
4. Push the search icon in the lower right menu.
5. Write "fichte" into the search field.
Expected Result:
- Firs (Latin Picea, German "Fichten") are part of the search results in addition to English matches.
- Matches on english data fields are ranked above english matches.
Actual Result: Only plants with the name firs.
Test Result: ⚠️
Notes: I can see plants with the name spruce, but where are the plants with the name firs?

TC-008 - Heatmap

SKIPPED

TC-009 - Timeline

Description: Change the date of the map to 'hide' plantings.
Preconditions:
- User must be on the map planning screen.
Test Steps:
1. Add a planting to the map.
2. Click on the date selection on the bottom of the screen.
3. Navigate to a date in the past.
4. Wait 1 second.
Expected Result:
- The indicator was briefly blue, indicating a loading state.
- The indicator beside the input is green.
- The Date on the bottom/right corner of the screen shows a date in the past.
- The planting previously planted is gone.
Actual Result:
Test Result: ⚠️
Notes: Issue #699, image loading error was present.

TC-010 - Timeline

Description: Change the date of the map to 'unhide' plantings.
Preconditions:
- User must be on the map planning screen.
Test Steps:
1. Add a planting to the map.
2. Click on the date selection on the bottom of the screen.
3. Navigate to a date in the past.
4. Wait 1 second.
5. Navigate to today.
Expected Result:
- The indicator was briefly blue, indicating a loading state.
- The indicator beside the input is green.
- The Date on the bottom/right corner of the screen shows the current day.
- The planting previously planted was gone while being in the past.
- The planting is visible again.
Actual Result:
Test Result: ⚠️
Notes: Issue #699, image loading error was present.

TC-011 - Timeline

Description: Change the add_date of a planting to 'hide' it.
Preconditions:
- User must be on the map planning screen.
Test Steps:
1. Add a planting to the map.
2. Click on the planting.
3. Click on the Add Date date selector in the left lower toolbar.
4. Change the date to a date in the future.
Expected Result:
- The indicator was briefly blue, indicating a loading state.
- The indicator beside the input is green.
- The planting previously planted is gone.
Actual Result:
Test Result: ✔️
Notes:

TC-012 - Timeline

Description: Change the remove_date of a planting to 'hide' it.
Preconditions:
- User must be on the map planning screen.
- The plants date has to be in the past.
Test Steps:
1. Add a planting to the map.
2. Click on the planting.
3. Click on the Remove Date date selector in the left lower toolbar.
4. Change the date to today.
Expected Result:
- The indicator was briefly blue, indicating a loading state.
- The indicator beside the input is green.
- The planting previously planted is gone.
Actual Result:
Test Result: ✔️
Notes:

TC-013 - Timeline

Description: Change the add_date of a planting to 'unhide' it.
Preconditions:
- User must be on the map planning screen.
Test Steps:
1. Add a planting to the map.
2. Click on the planting.
3. Click on the Add Date date selector in the left lower toolbar.
4. Change the date to a date in the future.
5. Wait one second
6. Remove the date
Expected Result:
- The indicator was briefly blue, indicating a loading state.
- The indicator beside the input is green.
- The planting previously planted was gone while its add_date was in the future.
- The planting is visible now with its add_date unset.
Actual Result: The plant did not appear again.
Test Result: ❌
Notes: Was tested multiple times and on a fresh map.

TC-014 - Base Layer

Description: Check whether the maps background image is displayed correctly.
Preconditions:
- A map has been created.
- The user has navigated to the map.
- The base layer has to be selected as the active layer.
Test Steps:
1. Select a base layer image.
2. Set the base layer rotation to 45 degrees.
3. Scale the base layer image to 50 px per meter.
4. Close and reopen the current map.
Expected Result:
- The selected base layer image is displayed after it has been selected.
- Applying rotation was successful (the image is rotated by 45 degrees).
- Applying scale was successful (the image is twice as large).
- The state of the base layer does not change when closing and reopening the map.
Actual Result:
Test Result: ✔️
Notes:

TC-015 - Grid

Description: Display a point grid on the screen.
Preconditions:
- User must be on the map screen.
Test Steps:
1. Press the grid button in the left upper menu bar.
2. Zoom all the way in.
3. Zoom all the way out.
Expected Result:
- The grid is displayed.
- Each press on the grid button toggles the grid of/on.
- Zooming in, grid spacing should switch from one meter to ten centimeters.
- Zooming out, grid spacing should switch ten centimeters to one meter to ten meter.
Actual Result:
Test Result: ✔️
Notes:

Manual Test Report (v0.3 case study release)

General

Tester: Yvonne Markl
Date/Time: 26 July 2023
Duration: ~ 50 minutes
Commit/Tag: 4e0bdc0e173f113ac0c155e012e6a68ff846a991
Setup: dev.permaplant.net
Planned tests: 14
Executed tests: 14
✔️Passed tests: 14
⚠️Problematic tests: 5
❌Failed tests: 0

Error Analysis

TC-002: Bei Language Switch popt nochmal "Hallo Yvonne" auf
TC-005:
- Ich war auf Deutsch und die Tour wurde auf Englisch gestartet. #710
- Hab die Tour mit X weggeklickt, jetzt kann ich sie gar nicht mehr aufrufen. #711
⚠️ PTC-006: je weiter unten, umso abweichendere Suchergebnisse, z.B. "Lacinato (Brassica oleracea acephala 'Lacinato')" --> kommt "tomato" nicht vor
⚠️ PTC-007:
- zu 'precondition' gehört auch 'English has been selected'
- Icons in search are missing #712
⚠️ PTC-013: "The planting is visible now with its add_date unset." --> bei mir muss ich immer erst das Kartendatum ändern (z.B. 1 Tag zurückspringen), dann erst wird die Pflanze wieder angezeigt
⚠️ PTC-014: "The selected base layer image is displayed after it has been selected." Image wurde erst angezeigt, als ich Rotation und Skalierung eingestellt hatte, evtl. #662
⚠️ PTC-015:
- "Press the grid button in the left upper menu bar." --> dann ist Grid DEaktiviert!
- "Zoom all the way in." ---> site becomes unresponsive

Manual Test Report (v0.3.1)

General

Tester: Aydan Namdar Ghazani
Date/Time: 08 August 2023
Duration: 12 minutes
Commit/Tag: master 25624e3
Setup: localhost
Planned tests: 17
Executed tests: 16
✔️Passed tests: 16
⚠️Problematic tests: 0
❌Failed tests: 0
Skipped tests: 1

Error Analysis

No errors occurred.

Closing remarks

How is the current state of the software?

The software is in a fully working state with no issues.

Have the quality objectives been achieved?

There were no defined quality objectives at this time.

What are the consequences drawn from the current state, including: how can future errors be avoided, how can the development process be improved?

It worked quite well! More tests could be automated to decrease manual effort for testing.

Description: Successfully login to PermaplanT
Preconditions:
Test Steps:
1. Press the login button on the navbar.
2. Enter credentials.
3. Press Login.
Expected Result:
- Get redirected to the homepage.
- Be logged in.
- See a Hello message pop up.
Actual Result:
Test Result: ✔️
Notes:

TC-002 - Translation

Description: Switch language on website
Preconditions:
Test Steps:
1. Change the language in the navbar
Expected Result:
- Language should be changed after selecting a new one.
Actual Result:
Test Result: ✔️
Notes:

TC-003 - Use Case: Map Creation

Description: Successfully create a new map.
Preconditions:
- Be logged in.
Test Steps:
1. Go to the map editor page.
2. Create a new map.
3. Enter valid stuff.
Expected Result:
- Map should be successfully created.
Actual Result:
Test Result: ✔️
Notes:

TC-004 - Map Creation (Negative)

Description: Can't create a map with a name that exists
Preconditions:
- Be logged in.
Test Steps:
1. Go to the map editor page.
2. Create a map with a name that already exists.
3. Enter valid stuff.
Expected Result:
- Map should not be created.
- Error message pops up on the top right.
Actual Result:
Test Result: ✔️
Notes:

TC-005 - Plant Search

Description: Show a selection of plants if the search input is empty.
Preconditions:
- No search input has been provided in the plant search.
Test Steps:
1. Navigate to the map page.
2. Select a map.
3. Select the plant layer in the right map menu.
4. Push the search icon in the lower right menu.
Expected Result:
- A selection of plants is shown to the user.
Actual Result:
Test Result: ✔️
Notes:

TC-006 - Plant Search

Description: Return expected results for a given search in the selected language.
Preconditions:
- The search term "tomato" has been typed into the search field.
Test Steps:
1. Navigate to the map page.
2. Select a map.
3. Select the plant layer in the right map menu.
4. Push the search icon in the lower right menu.
5. Write "tomato" into the search field.
Expected Result:
- The plants shown contain the string "tomato" in part of the datacolumns as outlined in the usecase document.
Actual Result:
Test Result: ✔️
Notes:

TC-007 - Plant Search

Description: Returns results for searches in the language that was selected.
Preconditions:
- Language English has been selected
Test Steps:
1. Navigate to the map page.
2. Select a map.
3. Select the plant layer in the right map menu.
4. Push the search icon in the lower right menu.
5. Write "Tomato" and "Potato" into the search field.
Expected Result:
- "Tomato" and "Potato" should be the first match.
Actual Result:
Test Result: ✔️
Notes:

TC-008 - Heatmap

SKIPPED

TC-009 - Timeline

Description: Change the date of the map to 'hide' plantings.
Preconditions:
- User must be on the map planning screen.
Test Steps:
1. Add a planting to the map.
2. Click on the date selection on the bottom of the screen.
3. Navigate to a date in the past.
4. Wait 1 second.
Expected Result:
- The indicator was briefly blue, indicating a loading state.
- The indicator beside the input is green.
- The Date on the bottom/right corner of the screen shows a date in the past.
- The planting previously planted is gone.
Actual Result:
Test Result: ✔️
Notes:

TC-010 - Timeline

Description: Change the date of the map to 'unhide' plantings.
Preconditions:
- User must be on the map planning screen.
Test Steps:
1. Add a planting to the map.
2. Click on the date selection on the bottom of the screen.
3. Navigate to a date in the past.
4. Wait 1 second.
5. Navigate to today.
Expected Result:
- The indicator was briefly blue, indicating a loading state.
- The indicator beside the input is green.
- The Date on the bottom/right corner of the screen shows the current day.
- The planting previously planted was gone while being in the past.
- The planting is visible again.
Actual Result:
Test Result: ✔️
Notes:

TC-011 - Timeline

Description: Change the add_date of a planting to 'hide' it.
Preconditions:
- User must be on the map planning screen.
Test Steps:
1. Add a planting to the map.
2. Click on the planting.
3. Click on the Add Date date selector in the left lower toolbar.
4. Change the date to a date in the future.
Expected Result:
- The indicator was briefly blue, indicating a loading state.
- The indicator beside the input is green.
- The planting previously planted is gone.
Actual Result:
Test Result: ✔️
Notes:

TC-012 - Timeline

Description: Change the remove_date of a planting to 'hide' it.
Preconditions:
- User must be on the map planning screen.
- The plants date has to be in the past.
Test Steps:
1. Add a planting to the map.
2. Click on the planting.
3. Click on the Remove Date date selector in the left lower toolbar.
4. Change the date to today.
Expected Result:
- The indicator was briefly blue, indicating a loading state.
- The indicator beside the input is green.
- The planting previously planted is gone.
Actual Result:
Test Result: ✔️
Notes:

TC-013 - Timeline

Description: Change the add_date of a planting to 'unhide' it.
Preconditions:
- User must be on the map planning screen.
Test Steps:
1. Add a planting to the map.
2. Click on the planting.
3. Click on the Add Date date selector in the left lower toolbar.
4. Change the date to a date in the future.
5. Wait one second
6. Remove the date
Expected Result:
- The indicator was briefly blue, indicating a loading state.
- The indicator beside the input is green.
- The planting previously planted was gone while its add_date was in the future.
- The planting is visible now with its add_date unset.
Actual Result:
Test Result: ✔️
Notes:

TC-014 - Base Layer

Description: Check whether the maps background image is displayed correctly.
Preconditions:
- A map has been created.
- The user has navigated to the map editor.
- The base layer has to be selected as the active layer.
Test Steps:
1. Select a base layer image.
2. Set the base layer rotation to 45 degrees.
3. Scale the base layer image to 50 px per meter.
4. Close and reopen the current map.
Expected Result:
- The selected base layer image is displayed after it has been selected.
- Applying rotation was successful (the image is rotated by 45 degrees).
- Applying scale was successful (the image is twice as large).
- The state of the base layer does not change when closing and reopening the map.
Actual Result:
Test Result: ✔️
Notes:

TC-015 - Grid

Description: Display a point grid on the screen.
Preconditions:
- User must be in the map editor.
Test Steps:
1. Press the grid button in the left upper menu bar.
2. Zoom all the way in.
3. Zoom all the way out.
Expected Result:
- The grid is not displayed anymore.
- Each press on the grid button toggles the grid off/on.
- Zooming in, grid spacing should switch from one meter to ten centimeters.
- Zooming out, grid spacing should switch ten centimeters to one meter to ten meter.
Actual Result:
Test Result: ✔️
Notes: The grid scale is badly visible on the top left.

TC-016 - Map Editor Guided Tour

Description: Check whether the Guided Tour leaves the Map Editor in its original state.
Preconditions:
- User must not have completed the Guided Tour prior.
- User must be on the map editor screen.
Test Steps:
1. Follow the Guided Tour until its end.
2. Do every step exactly as stated.
Expected Result:
- There are no plants on the map.
- The map date is set to the current date.
- Placement mode is not active.
Actual Result:
Test Result: ✔️
Notes:

TC-017 - Map Editor Guided Tour

Description: Guided Tour only shows when not completed or explicitly cancelled.
Preconditions:
- User must not have completed the Guided Tour prior.
- User must be on the map editor screen.
Test Steps:
1. Leave the page by entering a different URL or using the browsers navigate back button.
2. Return to the map editor screen.
3. Use the cancel button on the Tour step or press ESC.
4. Reload the page.
Expected Result:
- The Guided Tour will show again after returning to the map editor screen.
- After the page reload, the Guided Tour will not be displayed.
Actual Result:
Test Result: ✔️
Notes:

Manual Test Report (v0.3.2)

General

Tester: Markus Raab
Date/Time: 07 August 2023
Duration: 15 Min
Commit/Tag: bcb1c1a73abe9659f50a085762c5b7eec233f7e8
Setup: www.permaplant.net
Planned tests: 14
Executed tests: 14
✔️Passed tests: 14
⚠️Problematic tests: 0
❌Failed tests: 0

Error Analysis

TC-015: browser hangs when zooming completely in #800

Manual Test Report (v0.3.3)

General

Tester: Aydan Namdar Ghazani
Date/Time: 15 September 2023
Duration: ~10 minutes
Commit/Tag: af6b307
Setup: dev.permaplant.net
Planned tests: 11
Executed tests: 8
✔️Passed tests: 5
⚠️Problematic tests: 3
❌Failed tests: 0

Error Analysis

No errors occured during the test.

Closing remarks

How is the current state of the software?

The software is in a good state.

Have the quality objectives been achieved?

There were no defined quality objectives at this time.

What are the consequences drawn from the current state, including: how can future errors be avoided, how can the development process be improved?

The test protocol can be improved. There is no need to write testcases for features that are not implemented yet.

Testcases

Plant Search

Description: Show a selection of plants if the search input is empty.
Given I am on a map page with the plant layer active
When I have an empty search box
Then I can see various plants as results
Test Result: ✔️

Heatmap

Description: Test whether the heatmap endpoints generates the image correctly.
Given I am on a map page with the plant layer active
When I start planting a plant
Then I see suitable places for that plant
Test Result: Not Implemented

Base Layer

Description: Check whether the maps background image is displayed correctly.
Given I am on a map page with the base layer active
When I select a base layer image
Then I can see the base layer image on the canvas
Test Result: ✔️

Grid

Description: Display a point grid on the screen.
Given I am on a map page
When I Zoom in or out
Then the grid spacing is changing
Test Result: ✔️

Map Editor Guided Tour

Description: Check whether the Guided Tour leaves the Map Editor in its original state.
Given I am on a map page
When I do the Guided Tour
Then after I have done the Guided Tour the map is the same as before
Actual Result:
Test Result: ⚠️
Notes: Was not able to test, since my user already performed the tour in the past

Map Editor Guided Tour

Description: Guided Tour shows when not completed.
Given I am on a map page
When I have not completed the Guided Tour
Then I can do the Guided Tour at any time
Actual Result:
Test Result: ⚠️
Notes: Was not able to test, since my user already performed the tour in the past

Map Editor Guided Tour

Description: Guided Tour only shows when not completed or explicitly cancelled.
Given I am on a map page
When I have not completed the Guided Tour
Then I can interrupt the Tour at any time and come back later
Actual Result:
Test Result: ⚠️
Notes: Was not able to test, since my user already performed the tour in the past

Edit seed

Description: Edit seed.
Preconditions:
- User is on the view seed page.
Test Steps:
1. Press Button "Edit seed"
2. Change an attribute of the seed.
3. Submit the form.
4. Repeat steps 1 through 3 for every seed attribute.
Expected Result:
- The seed attributes updated successfully.
Test Result: ✔️

Delete seed

Description: Edit seed.
Preconditions:
- User is on the view seed page.
Test Steps:
1. Press Button "Delete seed"
Expected Result:
- The selected seed is no longer available.
Test Result: ✔️

Chat: Create conversation

Description: A conversation can be created
Given I am on the chat page
When I create a new conversation
Then I can see the conversation in the conversation list
Actual Result:
Test Result: Not Implemented
Notes: Currently only works with CORS disabled.

Chat: Send message

Description: Send a message to a Nextcloud conversation.
Given I am on the chat page
When I select a conversation
Then I can send messages in that conversation
Actual Result:
Test Result: Not Implemented
Notes: Currently only works with CORS disabled.

Manual Test Report (v0.3.4)

General

Tester: Aydan Namdar Ghazani
Date/Time: 14. October 2023
Duration: ~5 minutes
Commit/Tag: 1c3b54a
Setup: dev.permaplant.net
Planned tests: 8
Executed tests: 8
✔️Passed tests: 8
⚠️Problematic tests: 0
❌Failed tests: 0

What are the consequences drawn from the current state, including: how can future errors be avoided, how can the development process be improved?

We should remove tests from the protocol which are not implemented yet (Heatmap, Chat)

Testcases

Plant Search

Description: Show a selection of plants if the search input is empty.
Given I am on a map page with the plant layer active
When I have an empty search box
Then I can see various plants as results
Test Result: ✔️

Base Layer

Description: Check whether the maps background image is displayed correctly.
Given I am on a map page with the base layer active
When I select a base layer image
Then I can see the base layer image on the canvas
Test Result: ✔️

Grid

Description: Display a point grid on the screen.
Given I am on a map page
When I Zoom in or out
Then the grid spacing is changing
Test Result: ✔️

Map Editor Guided Tour

Description: Check whether the Guided Tour leaves the Map Editor in its original state.
Given I am on a map page
When I do the Guided Tour
Then after I have done the Guided Tour the map is the same as before
Actual Result:
Test Result: ✔️

Map Editor Guided Tour

Description: Guided Tour shows when not completed.
Given I am on a map page
When I have not completed the Guided Tour
Then I can do the Guided Tour at any time
Actual Result:
Test Result: ✔️

Map Editor Guided Tour

Description: Guided Tour only shows when not completed or explicitly cancelled.
Given I am on a map page
When I have not completed the Guided Tour
Then I can interrupt the Tour at any time and come back later
Actual Result:
Test Result: ✔️

Edit seed

Description: Edit seed.
Preconditions:
- User is on the view seed page.
Test Steps:
1. Press Button "Edit seed"
2. Change an attribute of the seed.
3. Submit the form.
4. Repeat steps 1 through 3 for every seed attribute.
Expected Result:
- The seed attributes updated successfully.
Test Result: ✔️

Delete seed

Description: Edit seed.
Preconditions:
- User is on the view seed page.
Test Steps:
1. Press Button "Delete seed"
Expected Result:
- The selected seed is no longer available.
Test Result: ✔️

Manual Test Report (v0.3.5)

General

Tester: Aydan Namdar Ghazani
Date/Time: 11. November 2023
Duration: 5 minutes
Commit/Tag: 42000aa
Setup: dev.permaplant.net
Planned tests: 8
Executed tests: 8
✔️Passed tests: 8
⚠️Problematic tests: 0
❌Failed tests: 0

What are the consequences drawn from the current state, including: how can future errors be avoided, how can the development process be improved?

None

Testcases

Plant Search

Description: Show a selection of plants if the search input is empty.
Given I am on a map page with the plant layer active
When I have an empty search box
Then I can see various plants as results
Test Result: ✔️

Base Layer

Description: Check whether the maps background image is displayed correctly.
Given I am on a map page with the base layer active
When I select a base layer image
Then I can see the base layer image on the canvas
Test Result: ✔️

Grid

Description: Display a point grid on the screen.
Given I am on a map page
When I Zoom in or out
Then the grid spacing is changing
Test Result: ✔️

Map Editor Guided Tour

Description: Check whether the Guided Tour leaves the Map Editor in its original state.
Given I am on a map page
When I do the Guided Tour
Then after I have done the Guided Tour the map is the same as before
Actual Result:
Test Result: ✔️

Map Editor Guided Tour

Description: Guided Tour shows when not completed.
Given I am on a map page
When I have not completed the Guided Tour
Then I can do the Guided Tour at any time
Actual Result:
Test Result: ✔️

Map Editor Guided Tour

Description: Guided Tour only shows when not completed or explicitly cancelled.
Given I am on a map page
When I have not completed the Guided Tour
Then I can interrupt the Tour at any time and come back later
Actual Result:
Test Result: ✔️

Edit seed

Description: Edit seed.
Preconditions:
- User is on the view seed page.
Test Steps:
1. Press Button "Edit seed"
2. Change an attribute of the seed.
3. Submit the form.
4. Repeat steps 1 through 3 for every seed attribute.
Expected Result:
- The seed attributes updated successfully.
Test Result: ✔️

Delete seed

Description: Edit seed.
Preconditions:
- User is on the view seed page.
Test Steps:
1. Press Button "Delete seed"
Expected Result:
- The selected seed is no longer available.
Test Result: ✔️

Manual Test Report (v0.3.6)

General

Tester: Aydan Namdar Ghazani
Date/Time: 21. November 2023
Duration: 5 minutes
Commit/Tag: 671cab1
Setup: localhost
Planned tests: 6
Executed tests: 6
✔️Passed tests: 6
⚠️Problematic tests: 0
❌Failed tests: 0

What are the consequences drawn from the current state, including: how can future errors be avoided, how can the development process be improved?

None

Testcases

Plant Search

Description: Show a selection of plants if the search input is empty.
Given I am on a map page with the plant layer active
When I have an empty search box
Then I can see various plants as results
Test Result: ✔️

Base Layer

Description: Check whether the maps background image is displayed correctly.
Given I am on a map page with the base layer active
When I select a base layer image
Then I can see the base layer image on the canvas
Test Result: ✔️

Grid

Description: Display a point grid on the screen.
Given I am on a map page
When I Zoom in or out
Then the grid spacing is changing
Test Result: ✔️

Map Editor Guided Tour

Description: Check whether the Guided Tour leaves the Map Editor in its original state.
Given I am on a map page
When I do the Guided Tour
Then after I have done the Guided Tour the map is the same as before
Actual Result:
Test Result: ✔️

Map Editor Guided Tour

Description: Guided Tour shows when not completed.
Given I am on a map page
When I have not completed the Guided Tour
Then I can do the Guided Tour at any time
Actual Result:
Test Result: ✔️

Map Editor Guided Tour

Description: Guided Tour only shows when not completed or explicitly cancelled.
Given I am on a map page
When I have not completed the Guided Tour
Then I can interrupt the Tour at any time and come back later
Actual Result:
Test Result: ✔️

Manual Test Report (v0.4.0)

General

Tester: Filip Markovic
Date/Time: 10.04.2024
Duration: 20 minutes
Commit/Tag: 5790350
Setup: dev.permaplant.net
Planned tests: 10
Executed tests: 10
✔️Passed tests: 10
⚠️Problematic tests: 0
❌Failed tests: 0

Error Analysis

When logging out while in a map, 4 error toast messages get shown on screen.

When logging out while in a map, 4 error toast messages get shown on screen.
Error has not been previously specified.
Class 6: Cosmetic issue

Closing remarks

How is the current state of the software?

Software looks good and working to me!

Have the quality objectives been achieved?

No defined quality objectives.

What are the consequences drawn from the current state, including: how can future errors be avoided, how can the development process be improved?

No drawn consquences.

Plant Search

Description: Show a selection of plants if the search input is empty.
Given I am on a map page with the plant layer active
When I have an empty search box
Then I can see various plants as results
Actual Result:
Test Result: ✔️
Notes:

Layer opacity

Description: Check whether the opacity of a layer changes.
Given I am on a map page with a base layer image configured
When dragging the slider for the base layer in the layer section of the toolbar to 50%
Then I can see the change in opacity of the base layer image
When I change the size of the toolbar
Then I can see the slider and the filling change in size proportionally. Therefore 50% of the slider should be filled.
Actual Result:
Test Result: ✔️ (took some time for me to see that the layers at the top right are sliders.)
Notes:

Base Layer

Description: Check whether the maps background image is displayed correctly.
Given I am on a map page with the base layer active
When I select a base layer image
Then I can see the base layer image on the canvas
Actual Result:
Test Result: ✔️
Notes:

Grid

Description: Display a point grid on the screen.
Given I am on a map page
When I Zoom in or out
Then the grid spacing is changing
Actual Result:
Test Result: ✔️
Notes:

Map Editor Guided Tour

Description: Check whether the Guided Tour leaves the Map Editor in its original state.
Given I am on a map page
When I do the Guided Tour
Then after I have done the Guided Tour the map is the same as before
Actual Result:
Test Result: ✔️
Notes:

Map Editor Guided Tour

Description: Guided Tour shows when not completed.
Given I am on a map page
When I have not completed the Guided Tour
Then I can do the Guided Tour at any time
Actual Result:
Test Result: ✔️
Notes:

Map Editor Guided Tour

Description: Guided Tour only shows when not completed or explicitly cancelled.
Given I am on a map page
When I have not completed the Guided Tour
Then I can interrupt the Tour at any time and come back later
Actual Result:
Test Result: ✔️
Notes:

Additional name on map: plant labels

Description: Test additional names being displayed properly.
Given I am on the map page with the plants layer active
When I create a new plant from a seed.
Then I can see the additional name on the label when hovering over the plant.
Actual Result:
Test Result: ✔️
Notes: The additional name must also be visible when a different account views the same map in parallel.

Description: Test additional names being displayed properly.
Given I am on the map page with the plants layer active
When I create a new plant from a seed.
When I click on the new plant icon.
Then I can see the additional name in the left toolbars heading.
Actual Result:
Test Result: ✔️
Notes: The additional name must also be visible when a different account views the same map in parallel.

Additional name on map: updates

Description: Test additional names being displayed properly.
Given I am on the map page with the plants layer active
When I create a new plant from a seed.
When I go to the inventory page and change the seeds name.
Then I can see the changes in the plant label and left toolbar.
Actual Result:
Test Result: ✔️
Notes: The additional name must also be visible when a different account views the same map.

Manual Test Report (v0.4.1)

General

Tester: Filip Markovic
Date/Time: 28.05.2024, 14:55
Duration: 20 minutes
Commit/Tag: 3c5eb11fbabf1cb6ce6bc64e5801c3be6bfcccb7
Setup: dev.permaplant.net
Planned tests: 23
Executed tests: 23
✔️Passed tests: 23
⚠️Problematic tests: 0
❌Failed tests: 0

Error Analysis

No major errors were encountered

Closing remarks

How is the current state of the software?

Software looks good and working to us!

Have the quality objectives been achieved?

No defined quality objectives.

What are the consequences drawn from the current state, including: how can future errors be avoided, how can the development process be improved?

No drawn consquences.

Plant Search

Description: Show a selection of plants if the search input is empty.
Given I am on a map page with the plant layer active
When I have an empty search box
Then I can see various plants as results
Actual Result:
Test Result: ✔️
Notes:

Layer opacity

Description: Check whether the opacity of a layer changes.
Given I am on a map page with a base layer image configured
When dragging the slider for the base layer in the layer section of the toolbar to 50%
Then I can see the change in opacity of the base layer image
When I change the size of the toolbar
Then I can see the slider and the filling change in size proportionally. Therefore 50% of the slider should be filled.
Actual Result:
Test Result: ✔️
Notes:

Base Layer

Description: Check whether the maps background image is displayed correctly.
Given I am on a map page with the base layer active
When I select a base layer image
Then I can see the base layer image on the canvas
Actual Result:
Test Result: ✔️
Notes:

Grid

Description: Display a point grid on the screen.
Given I am on a map page
When I Zoom in or out
Then the grid spacing is changing
Actual Result: The jump when zooming out too much is strong
Test Result: ✔️
Notes:

Map Editor Guided Tour

Description: Check whether the Guided Tour leaves the Map Editor in its original state.
Given I am on a map page
When I do the Guided Tour
Then after I have done the Guided Tour the map is the same as before
Actual Result:
Test Result: ✔️
Notes:

Map Editor Guided Tour

Description: Guided Tour shows when not completed.
Given I am on a map page
When I have not completed the Guided Tour
Then I can do the Guided Tour at any time
Actual Result:
Test Result: ✔️
Notes:

Map Editor Guided Tour

Description: Guided Tour only shows when not completed or explicitly cancelled.
Given I am on a map page
When I have not completed the Guided Tour
Then I can interrupt the Tour at any time and come back later
Actual Result:
Test Result: ✔️
Notes:

Additional name on map: plant labels

Description: Test additional names being displayed properly.
Given I am on the map page with the plants layer active
When I create a new plant from a seed.
Then I can see the additional name on the label when hovering over the plant.
Actual Result:
Test Result: ✔️
Notes: The additional name must also be visible when a different account views the same map in parallel.

Description: Test additional names being displayed properly.
Given I am on the map page with the plants layer active
When I create a new plant from a seed.
When I click on the new plant icon.
Then I can see the additional name in the left toolbars heading.
Actual Result:
Test Result: ✔️
Notes: The additional name must also be visible when a different account views the same map in parallel.

Additional name on map: updates

Description: Test additional names being displayed properly.
Given I am on the map page with the plants layer active
When I create a new plant from a seed.
When I go to the inventory page and change the seeds name.
Then I can see the changes in the plant label and left toolbar.
Actual Result:
Test Result: ✔️
Notes: The additional name must also be visible when a different account views the same map.

Layer Management: Initial Order of Layers

Description: Test initial order of layers
When I create a new map
Then Base Layer is at bottom of layer list and Plant Layer is on top of layer list
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Correct konva rendering of layer order on new map

Description: Test correct rendering order of konva layers.
Given I am on a new map
When I add a background image in Base Layer
When I add a filled rectangle in Drawing Layer
When I add a plant in plant layer
Then Plant in is front of rectangle and rectangle is in front of background image
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Renaming of layer

Description: Test if Drawing Layer can be renamed.
Given I am on a new map
When I rename the Drawing Layer
Then The new name is visible in the layer list
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Creation of new layer

Description: Test if new layer can be created.
Given I am on a new map
When I select a layer and create a new one
Then The new layer is visible above currently selected layer
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Change order of layers

Description: Test if the order of layers can be updated correctly.
Given I am on a map with 2 drawing layers with overlapping rectangles
When I select the upper Drawing Layer and move it below the other one
Then The order in the layer list is updated and the rectangle of the new upper drawing layer is shown in front of the lower one on the map.
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Delete Drawing Layer

Description: Test if Drawing Layer can be deleted
Given I am on a map with some drawing on a Drawing Layer.
When I delete the Drawing Layer
Then The layer disappears from layer list and drawings are deleted from map
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Deletion of Plant Layer not possible

Description: Test if deletion of Plant layer is disabled
Given I am on a new map.
When I select the Plant Layer
Then Button to delete layer is disabled
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Deletion of Base Layer not possible

Description: Test if Deletion of Base layer is disabled
Given I am on a new map.
When I select the Base Layer
Then Button to delete layer is disabled
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Undo deletion

Description: Test if deleted layer can be restored
Given I am on a map with some drawing on a drawing layer.
When I delete the drawing layer
Then Layer disappears from layer list and drawings are deleted from map
When I press undo
Then Layer appears again at same position as it was before deletion and drawings are visible again.
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Top layer cannot be moved up

Description: Test if the top layer cannot be moved up
Given I am on a new map.
When I select the top layer.
Then Button to to move layer up is disabled
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Bottom layer cannot be moved down

Description: Test if the bottom layer cannot be moved down
Given I am on a new map.
When I select the bottom layer.
Then Button to to move layer down is disabled
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Renaming of Plant Layer not possible

Description: Test if Renaming of Plant layer is not possible
Given I am on a new map.
When I select the Plant Layer
Then Button to rename layer is disabled
Actual Result:
Test Result: ✔️
Notes:

Layer Management: Renaming of Base Layer not possible

Description: Test if Renaming of Base layer is not possible
Given I am on a new map.
When I select the Base Layer
Then Button to rename layer is disabled
Actual Result:
Test Result: ✔️
Notes:

General

Tester:
Date/Time:
Duration:
Commit/Tag:
Setup: local build or dev.permaplant
Planned tests: -1
Executed tests: -1
✔️Passed tests: -1
⚠️Problematic tests: -1
❌Failed tests: -1

Error Analysis

Identifying the error: Is it indeed a genuine software defect, or is it a faulty test case, incorrect test execution, etc.?
Has the error already been identified in previous tests?
Error specifictation

Class 1: Faulty specification
Class 2: System crash
Class 3: Essential functionality is faulty
Class 4: Functional deviation or limitation
Class 5: Minor deviation
Class 6: Cosmetic issue

Priority

Level 1: Immediate resolution
Level 2: Fix in next version
Level 3: Correction will be done opportunistically
Level 4: Correction planning is still open

Closing remarks

How is the current state of the software?
Have the quality objectives been achieved?
What are the consequences drawn from the current state, including: how can future errors be avoided, how can the development process be improved?

Usecases

This folder contains all use cases of PermaplanT.

They are structured in folders by progress:

current: use case is currently worked on
assigned: use case is part of PermaplanT 1.0 (June 2024)
done: use case was successfully implemented
later: currently not being worked on due to priorities
draft: not being worked on and not yet ready for implementation

Done

A use case is done iff:

documented how changes/extensions should be done
closed all issues or wrote about left-overs in notes of use case
wrote in changelog about finished UC and added a link to it
wrote e2e test cases or extended the test protocol
added links from use case to implementation/documentation/test protocol
moved use case to folder "done"

Assigned Use Cases

Or usecases ready to be assigned.

Use Case: Buy Seeds

Summary

Scope: Seed Management
Level: User Goal
Actors: App User
Brief: The users buys missing seeds for the planned plants.
Assignee: Paul

Scenarios

Precondition:
- Already existing seeds are entered
- Plants are planted
- The user has opened the seed buying feature in the app.
Main success scenario:
- The user gets a suggestion which seeds to buy based on planted seeds minus existing seeds.
- The seeds are grouped by seeds that are not, partially or sufficiently stocked.
- The user adjusts the amount for the already existing seeds if wanted.
- After confirming the purchase, the bought seeds get added to the seed database.
Alternative scenario:
Error scenario: There is an error when the user attempts to purchase the seeds. In this case, the seed database stays unmodified and the user gets notified about the error.
Postcondition: The seed database contains all seeds as visible in the map.
Non-functional Constraints:

Use Case: Copy & Paste Between Users

Summary

Scope: All Layers, except Base
Level: User Goal
Actors: App User
Brief: The user can copy and paste a selection of elements, including succeeding crops, between his own map and a map of another user.
Assignee: Andrei

Scenarios

Precondition: User A has opened the app on a key-controlled device and has made a selection of elements on one of his maps that he wants to copy and paste into the map of another user B.
Main success scenario:
- User A copies the selection on his map.
  User A opens a map of user B.
  User A clicks anywhere on that map of user B.
  User A pastes the copied selection into user B's map.
  The pasted selection of elements is placed in user B's map at the position where user A's last click happened.
Alternative scenarios:
- Same as for Copy & Paste of Selection Within the Same Map, just with maps of two different users
- The user logs in.
  The user fails to paste the elements he copied in his previous session because they are removed from the 'copy-storage'.
Error scenarios:
- The user attempts to copy and paste a selection but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postconditions:
- The user's map contains the copied and pasted selection of elements.
- User A's map still contains the same elements as before the copying and pasting into user B's map.
- User B's map contains the pasted selection of elements which user A copied from one of his own maps.
Non-functional Constraints:
- Same as for Copy & Paste of Selection Within the Same Map
- For performance reasons and to minimize potential sources of error, the copied selection of elements should be persisted locally on the client side, i.e. in the browser's local storage.
- The new storage, i.e. the local storage, should be used for every Copy & Paste scenario to store and retrieve the latest copied elements.
- To avoid inconsistencies of all sorts, the new storage with the copied elements in it, should not be persisted beyond a user's session, i.e. it should cleared upon the user's next login.
Linked Use Cases:
- Copy & Paste of Selection Within the Same Map

Use Case: Copy & Paste Within the Same Map

Summary

Scope: All Layers, except Base
Level: User Goal
Actors: App User
Brief: The user can copy and paste a selection of elements, including succeeding crops, within one map.
Status: Andrei

Scenarios

Precondition: The user has opened the app on a key-controlled device and, on one of his maps, made a selection of elements that he wants to copy and paste into that same map.
Main success scenario:
- The user copies the selection by pressing CTRL-C.
  The user clicks anywhere on that same map.
  The user pastes the copied selection into the map by pressing CTRL-V.
  The pasted selection of elements is placed in the map at the user's last click position right before pasting.
Alternative scenarios:
- The user pastes a copied selection without having clicked anywhere else on the map after copying.
  The pasted selection is placed with a horizontal and vertical offset next to the copied selection.
- The user pastes a copied selection several times in a row.
  The pasted selections are each placed with a horizontal and vertical offset next to each other.
- The user pastes a copied selection while having other element(s) currently selected.
  The pasted selection is placed with a horizontal and vertical offset next to the currently selected element(s).
- The user pastes a copied selection having the wrong layer selected and a warning appears advising the correct layer.
  The user selects the correct layer and successfully pastes that selection of elements into it.
- The user presses CTRL-C without having anything selected.
  The user presses CTRL-V and no pasting happens because no elements have been copied.
- In a step #1, the user presses CTRL-C on a selection of elements.
  In a step #2, The user unselects that selection by clicking anywhere else on the map.
  The user presses CTRL-C without having anything selected.
  The user presses CTRL-V.
  The, in step #1, copied selection of elements is pasted into the map, placed where the user clicked in step #2 to unselect the copied elements.
- The user pastes a wrongly chosen selection of elements.
  The user uses the app's undo function to revert the pasting.
Error scenarios:
- The user attempts to copy and paste a selection but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postconditions:
- The user's map contains the copied and pasted selection of elements.
Non-functional Constraints:
- Alternatives (selected elements depend on which alternative layer is selected)
- Any copy & pasted element should have its own UUID in the map, i.e. it's a unique Konva node on the current canvas.
- Left-click, middle-click and right-click should be accepted for setting the target position of the next pasting.
- The shortcuts for copying and pasting (CTRL-C and CTRL-V) should be stored in a central place where future keybindings will be added too.
Linked Use Cases:

Development Progress

(this usecase) Copy & Paste of Selection Within the Same Map
This usecase should be done before any other Copy & Paste-related usecase.
It will contain the core logic of copying and pasting.
Copy & Paste of Selection via Icons
It can reuse everything implemented in the first usecase one-to-one.
Additionally it will add the logically-isolated possibility to copy and paste via icons plus the 'visibility-toggling' of the copy- and paste-icons' design.
Copy & Paste of Selection Between a User's Own Maps / Copy & Paste of Selection Between Maps of Different Users
Here, the storing of the copied elements will have to be moved from the app's map store to the client side, i.e. the browser's local storage.

Use Case: Crop Rotation

Summary

Scope: Crop Rotation
Level: User Goal
Actors: App User, Plant A, Plant B
Brief: The user gets information based on earlier or later plants for each location.
Assignee: Lukas

Scenarios

Precondition:
- The user has opened the app and sees either Heatmap or Relation Layer.
- A plant A has been on the same spot in the past as plant B is now.
- This plant A has a removal date before the adding date of plant B (remove_date of A < add_date of B).
- There is a positive or negative crop rotation effect between plant A and B, which can last from half a year to a predefined number of years.
Main success scenario:
- A positive effect is shown green in the heatmap on this spot before plant B is planted.
- A weak negative effect (within max in the relation table) is shown at least yellow in the heatmap on this spot before plant B is planted.
- A strong negative effect (within min in the relation table) is shown at least orange in the heatmap on this spot before plant B is planted.
- The relation layer shows an icon with text describing the specific crop rotation effect between plant A and B, e.g.:
  - "Strong negative crop rotation effect: Cabbage shouldn't be placed within the same year on the same spot."
  - "Nachteilige Fruchtfolge: Kohl braucht ein Jahr Anbaupause bevor wieder Kohl gepflanzt werden soll."
Alternative scenario:
- Without data or relation for A or B, nothing happens for the user and no additional information is provided.
Error scenario:
Postcondition:
Linked Use Cases:
- Heatmap
- Relation Layer
Notes:

Use Case: Fertilization Layer

Summary

Scope: Fertilization Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move, remove and delete fertilizers in their map in the layer.
Assignee: Lukas

Scenarios

Precondition: The user has opened the app and has selected the fertilization layer.
Main success scenario:
- The user successfully adds, edits, moves and removes fertilizers in their map in the fertilization layer.
- Fertilizers can be drawn using brushes of different sizes.
- The user can write a note which fertilization was used.
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario:
- If the user encounters technical issues or errors while using the fertilization layer, the platform should display an error message and allow the user to try again.
Postcondition: The user has successfully added, edited, moved, removed and deleted fertilizers in the fertilization layer.
Non-functional Constraints:
- Is a brushing layer
- Offline availability
- Performance: Map sizes with more than 1ha in 10000 raster elements (m²) per year should be usable without noticeable delays and acceptable memory overhead

Use Case: Hydrology Layer

Summary

Scope: Hydrology Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move, remove and delete wet or dry areas.
Assignee: Lukas

Scenarios

Precondition: The user has opened the app and has selected the hydrology layer.
Main success scenario:
- The user successfully adds, edits, moves, removes and deletes dry, wet and watery areas in the hydrology layer. For example: surface water runoff, natural reservoirs, gullies, rills, etc. This includes positioning the areas in the appropriate location.
- Default is moist.
- Dry, wet and watery areas can be added by a small (rills) or big brush (surface water) to draw on the hydrology layer.
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario: The user attempts to add, move or edit a moisture or dry area but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The user's map includes the added, edited, moved, removed or deleted moisture areas as desired.
Non-functional Constraints:
- Performance: Map sizes with more than 1ha in 10000 raster elements (m²) per year should be usable without noticeable delays and acceptable memory overhead

Use Case: Incomplete Groups

Summary

Scope: Plants Layer
Level: User Goal
Actors: App User
Brief: The user is informed about what plant groups need more planning.
Assignee: Stefanie

Scenarios

Precondition:
- The user has opened the app
- The plants layer is visible
- At least one plant is placed
- At least to one of the placed plants a companion plant can be added.
Main success scenario:
- Groups, where further companions are available, are visually highlighted.
Alternative scenario:
- No groups have further companions available. This is visually indicated.
Error scenario:
Postcondition:
- The user knows which groups need more attention.
Non-functional Constraints:

Use Case: Map Collaboration

Summary

Scope: Map Collaboration
Level: User Goal
Actors: Map Creator, Collaborator
Brief: Enable collaborators to modify a map.
Simplification: Without alternatives.
Assignee: Paul, Andrei

Scenarios

Precondition:
- A map creator creates a map or has created a map.
- At least one other collaborator is registered in Keycloak.
Main success scenario:
- The map creator chooses if the map is open to be viewed by every registered user or member (public/protected/private).
- The map creator searches for collaborators by their name.
- The map creator adds a collaborator found before (repeated as needed).
- The map creator can create alternatives of existing layers and designate which can be edited by collaborators.
Alternative scenario:
- The map creator removes a previously added collaborator.
Error scenario: The app can't send an invitation to a requested collaborator through network issues. In this case, the map creator should be informed by an error message and is prompted to try again.
Postcondition:
- Collaborators can modify the map like it is one of their own.
- Collaborators cannot modify map properties.
Non-functional Constraints:
- 30 collaborators can be added on one map.

Use Case: Map Timeline Range Selection

Summary

Scope: Map View
Level: User Goal
Actors: App User
Brief: The user can view the map over a range of consecutive points in time by using the timeline feature.
Assignee: Andrei

Scenarios

Precondition: The user has opened the app and selected a map.
Main success scenario:
- The user selects the timeline view and uses the scroll bar with a day/month/year granularity, or a date input that allows date range selection.
- Using the scroll bar, the user clicks and drags the mouse to span a range of dates.
- The user can only drag the selection up to the furthest event that happened in the past or the future.
- Dragging over the scroll bar hints which day/month/year represents the start and which the end of the selected date range.
- Finalizing the date selection updates the map to show the state of the garden over a range of points in time.
- Elements on the map that do not exist over the whole range of dates, appear grey.
- Elements on the map can be edited/moved/deleted, but not be added or removed.
Alternative scenario:
Error scenario:
- There is an error in the timeline display or navigation functionality. In this case, the app displays an error message and allows the user to try again.
- The user tries to add/remove elements while being in the active date range. In this case, the app displays an error message that adding/removing elements is not allowed.
Postcondition: The user successfully sees the map containing the elements in the desired range of dates.
Non-functional Constraints:
- Offline availability only within the current year
- Memory usage (other years get unloaded after some time if they are not used)
- Performance

Use Case: Map to PDF

Summary

Scope: Map View
Level: User Goal
Actors: App User
Brief: Users can generate a PDF file of the map.
Assignee: Andrei

Scenarios

Precondition:
The user has opened the app and navigated to the desired map view.
Main success scenario:
The app captures a screenshot of the current map view and generates a PDF file.
The app adds a header/footer to the PDF containing the current time, map timestamp, GPS coordinates, and scale.
The user receives the generated PDF file for printing or saving.
Alternative scenario:
Error scenario:
The app encounters an issue while generating the PDF file, such as insufficient storage space or an unexpected error.
Postcondition:
The user has successfully generated a printable PDF file containing the current map view and relevant metadata in the header/footer.
Non-functional Constrains:
The generated PDF should be compatible with common PDF readers and printers.
The option to generate a printable map should be easily accessible and understandable.

Use Case: New Member Notification

Summary

Scope: Notifications
Level: User Goal
Actors:
- App User which is newly registered: "new user"
- App User which existed beforehand: "existing user"
Brief: The user gets a notification when a new user joined.
Assignee: Andrei
Simplification: Every user gets notified for every new member.

Scenarios

Precondition:
- The new user is registered.
- The new user is located nearby (requires location settings of both users, nearby is a defined radius).
Main success scenario: The existing user gets a notification (email) which informs them about the new user.
Alternative scenario: One or both of the users have no location information: The user doesn't receive a notification.
Error scenario:
Postcondition:
Non-functional Constraints:

Use Case: Plant Database Update Notification

Summary

Scope: Notifications & Plant Management
Level: User Goal
Actors: App User
Brief: Notify users about updates of the plant database.
Assignee: Andrei (Frontend), Jannis (Backend)

Scenarios

Precondition:
The user has opened the app and has successfully logged in.
The plant database has been updated since the user's last login.
Main success scenario:
Upon login, the user receives a notification about the updated plant database if affected plants exist on the map or in the favorites and if:
light, water or soil requirements changed
edible status changed
warning was added (in plant database), e.g. "weed potential"
dates of sowing or raising changed
companions changed
The notification highlights plants that have changed.
The user adjusts their garden layout accordingly.
The user confirms that the updates were considered and goes back to normal mode.
Alternative scenario:
The user dismisses the notification without reviewing the updated plant positioning recommendations. The notification is accessible later from a designated area in the app.
The user decides to not receive updates of changed plants in the future.
Error scenario:
The app is unable to retrieve the updated plant database information due to connectivity issues or server problems.
Data synchronization issues: In cases where an application needs to synchronize data across multiple devices or platforms, errors or inconsistencies might arise, leading to data loss or conflicts.
Postconition:
The user is aware of the updated plant database and can make informed decisions about their garden layout based on the latest recommendations.
Non-functional Constrains:
The app should quickly retrieve and display plant database updates, providing a seamless user experience.
The notification system and plant management interface should be intuitive and easy to use.
The app should consistently inform users of plant database updates, ensuring that users are always aware of the latest recommendations.

Use Case: Remember Viewing State

Summary

Scope: Map
Level: User Goal
Actors: App User
Brief: The map's visibility settings are restored from the user's last session.
Status: Andrei

Scenarios

Precondition: The user is logged in and has opened a map.
Main success scenario:
- The user selects layer A.
  He zooms into the map.
  He scrolls/drags the map's viewport.
  He sets layer B invisible.
  He sets layer C with transparency.
  He turns off the grid display.
  He hides the plant labels.
  He closes the browser, opens it again and logs in. He opens the same map again which he edited in his previous session.
  He finds all the changes and settings from the last session being restored:
  - layer A selected
  - zoomed-in on the map
  - all plants visible on the map's viewport
  - layer B invisible
  - layer C has the same transparency
  - grid display turned off
  - plant labels hidden
Alternative scenario:
- The user does visibility changes on a map.
  He navigates to the seeds page.
  He uses browser-back to get back to the map.
  All the visibility changes the user applied before, are restored.
- The user does visibility changes on map A.
  He opens another map B and changes some visibility settings there too.
  He goes back to map A and finds all the visibility changes he did on map A, still being applied.
  He goes back to map B and sees that all the visibility settings he changed on map B, are still being set.
- The user does visibility changes on a map in browser A. He logs in in another browser B. He opens the same map in browser B. All the visibility changes the user applied to the map in browser A, are restored in browser B.
Error scenario: The app is experiencing technical difficulties and unable to restore one or more of the map's visibility settings, displaying an info message that the map's viewing state could not be fully restored.
Postcondition:
- The map is shown with the same visibility settings it had when the user left it the last time, which includes:
  - zoom
  - map's (x,y)-offset in the viewport
  - selected layer
  - all layers' visibility
  - grid display
  - plant labels display
Non-functional Constraints:
- Changes to maps while being in offline-mode, are not considered for restoring (for now).
- Zustand's persist middleware should be used to store a map's state in a storage of any kind - not only do we already use Zustand as our global state management library, but it also supports de-/serialization of Maps and Sets.
  Persist's partialize option should then be used to only store the 'restore-worthy' data of a map.
- Copy & Paste related data should not be restored, to not only reduce complexity of the storing/restoring- as well as the undo/redo-process, but also to prevent out-of-sync scenarios where copied elements are already deprecated/removed/outdated in the system/database. Besides that, applications offering the recovery of Copy & Paste state in a new session are extremely rare and therefore something the user does not necessarily expect to get.

Use Case: Soil Layer

Summary

Scope: pH Values Layer
Level: User Goal
Actors: App User
Brief: The user can add, move, remove, delete and edit areas of pH values and soil weight class in their map using the soil layer
Assignee: Lukas

Scenarios

Precondition: The user has opened the app and has selected the soil layer.
Main success scenario:
1. First the user globally tells a pH topsoil value, soil weight and yield grade.
2. Then the user successfully adds, moves, removes, deletes and edits:
  - pH value areas for topsoil
  - pH value areas for subsoil
  - soil weight class
  - yield grade in their map using the soil layer, where it differs from the global value. This includes positioning the pH value areas in the appropriate locations and adjusting their values as needed. A big brush is used to draw on the soil layer.
3. The user can check the values at individual spots by clicking on it.
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario: The user attempts to edit a soil weight class or pH value in a area that is not within the acceptable range and the app displays an error message. The previous values stay unmodified.
Postcondition: The user's map includes the added, moved or edited pH value areas as desired.
Non-functional Constraints:
- is a brushing layer
- The app must clearly communicate to the user the constraints for editing pH values in the soil layer.
- Performance: Map sizes with more than 1ha in 100 raster elements (in 1a=100m²) per year with 4 values per raster element should be usable without noticeable delays and acceptable memory overhead
Notes:
- pH values have one significant digit, not more (e.g. 4.5, 6.7, 8.4)

Use Case: Suggest Plants

Summary

Scope: Plants Layer
Level: User Goal
Actors: App User
Brief: The user gets plant suggestions that she would not have thought of herself.
Assignee: Lukas

Scenarios

Precondition:
- The user has opened the app.
- The plants layer is enabled.
- Plant(s) or a position on the map are selected.
Main success scenario:
- A choice of plants that
  1. work well with already placed plants and
  2. fit the environmental conditions
  3. have a high ecological value
  are presented to the user. Further more, the plants should be grouped by:
  - available inventory with early expiration days first
  - favourites of users
  - and lastly which were recently planted
- Within those suggestions the user can see what plants go well with each other.
- The user can see why these plants have a high ecological value. e.g.:
  - Attracts wildlife
  - Attracts pollinating insects
  - Is a nitrogen fixer
  - Is a cover crop
  - Are less commonly planted
  - etc.
Alternative scenario:
- No plant(s) or position are selected.
- Polyculture groups that fit the environmental conditions are suggested.
Error scenario:
- In case of any technical errors the users is notified about these.
- When there are no matches due to too many constraints the user is informed that she has to remove a plant and try again.
Postcondition:
- The user can consider plants she would have never though of herself.
Non-functional Constraints:
- Performance

Use Case: Watering Layer

Summary

Scope: Watering Layer
Level: User Goal
Actors: App User
Brief: The user can log watering events for parts of or the entire garden to track watering history and improve plant care.
Assignee: Lukas

Scenarios

Precondition:
- The user has opened the app and has selected the watering layer.
Main success scenario:
- The user brushes permanent infrastructure:
  - roofs etc. (watering needed despite of rain)
  - automatic irrigation (no watering needed there)
- The user logs a watering event:
  - by selecting individual plants
  - by brushing over the map
  - for all parts of the map which are defined (for e.g. rain, automatic watering, regular watering routine)
- The app saves the watering event with the current date.
- The watering history is visible to the user, providing an overview of past watering events.
Alternative scenario:
- The user accidentally adds, edits or moves an element and uses "undo" or "delete" functionality to correct the mistake.
Error scenario:
- The user attempts to log a watering event with invalid data (e.g., negative water amount).
Postconition:
- The watering history is updated, and the user can review the information to make informed decisions about watering plants in the future.
Non-functional Constrains:
- is a brushing layer
- The watering management feature should be easy to use and understand.
- The feature should work offline, allowing users to log watering events without an internet connection and synchronize the data when the connection is reestablished.

Current Use Cases

Use Case: Additional Layer

Summary

Scope: Additional Layer
Level: User Goal
Actors: App User
Brief: Users add, edit, move, remove and delete custom elements.
Assignee: Stefanie

Scenarios

Precondition: The user has opened the app and has selected the drawing layer.
Main success scenario:
- The user successfully adds, edits, moves, removes and deletes custom elements in three tabs:
  1. drawings
  - free drawings
  - ellipses
  - rectangles
  - polygons (consisting of lines and bezier helper-points, that can be created by dragging existing lines)
    - open without filling
    - closed with 3 different fillings
  - arrows (e.g. to indicate water flow)
  1. labels
  2. images
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario: The user attempts to add, move or edit a drawing but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The user's map includes the added, edited, moved, removed or deleted drawings as desired.
Non-functional Constraints:
- Performance: at least 1000 elements per year per drawing layer should be usable without noticeable delays and acceptable memory overhead

Use Case: Copy & Paste Between Own Maps

Summary

Scope: All Layers, except Base
Level: User Goal
Actors: App User
Brief: The user can copy and paste a selection of elements, including succeeding crops, between his own maps.
Assignee: Andrei

Scenarios

Precondition: The user has opened the app on a key-controlled device and made a selection of elements on his own map A that he wants to copy and paste into his own map B.
Main success scenario:
- The user copies the selection on map A.
  The user opens map B.
  The user clicks anywhere on map B.
  The user pastes the copied selection into map B.
  The pasted selection of elements is placed in map B at the user's last click position right before pasting.
Alternative scenarios:
- Same as for Copy & Paste of Selection Within the Same Map, just with two different maps of the same user
- The user logs in.
  The user fails to paste the elements he copied in his previous session because they are removed from the 'copy-storage'.
Error scenarios:
- The user attempts to copy and paste a selection but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postconditions:
- The user's map contains the copied and pasted selection of elements.
- The user's map A still contains the same elements as before the copying and pasting into map B.
- The user's map B contains the pasted selection of elements which he copied from his map A.
Non-functional Constraints:
- Same as for Copy & Paste of Selection Within the Same Map
- For performance reasons and to minimize potential sources of error, the copied selection of elements should be persisted locally on the client side, i.e. in the browser's local storage.
- The new storage, i.e. the local storage, should be used for every Copy & Paste scenario to store and retrieve the latest copied elements.
- To avoid inconsistencies of all sorts, the new storage with the copied elements in it, should not be persisted beyond a user's session, i.e. it should cleared upon the user's next login.
Linked Use Cases:
- Copy & Paste of Selection Within the Same Map

Use Case: Copy & Paste Via Icons

Summary

Scope: All Layers, except Base
Level: User Goal
Actors: App User
Brief: The user can copy and paste a selection of elements, including succeeding crops, by using the appropriate icons in the toolbar.
Assignee: Andrei

Scenarios

Precondition: The user has opened the app and has made a selection of elements that he wants to copy and paste.
Main success scenario:
- The user copies the selection by clicking on the copy icon in the toolbar.
  The user clicks anywhere on the map.
  The user pastes the copied selection into the map by clicking on the paste icon in the toolbar.
  The pasted selection of elements is placed at the user's last click position right before pasting.
Alternative scenario:
- Same as for Copy & Paste of Selection Within the Same Map, just with clicking on the icons in the toolbar instead of using the keyboard shortcuts
- The user copies the selection by pressing CTRL-C.
  The user clicks on the paste icon to paste the copied selection into the map.
- The user copies the selection by clicking on the copy icon.
  The user pastes the copied selection into the map by pressing CTRL-V.
Intercondition:
- The user sees the copy icon as disabled and greyed out because he has no elements selected.
- The user sees the paste icon as disabled and greyed out because he has not copied any element(s) in his current session yet.
- The user copies a selection of elements for the first time in his current session.
  The user sees the paste icon getting enabled and not being greyed out anymore.
- The user makes a selection of elements on the map, not having had anything selected right before.
  The user sees the copy icon getting enabled and not being greyed out anymore.
Error scenario:
- The user attempts to copy and paste a selection but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition:
- The user's map contains the copied and pasted selection of elements.
- The copy icon is disabled and greyed out because after pasting every selection is gone.
- The paste icon is enabled and not greyed out.
Non-functional Constraints:
- Same as for Copy & Paste of Selection Within the Same Map
- The icons' Look and Feel should always signal their current state, i.e. if they are enabled or disabled.
Linked Use Cases:
- Copy & Paste of Selection Within the Same Map

Use Case: GeoMap

Summary

Scope: GeoMap
Level: User Goal
Actors: App User
Brief: The user can view sites/maps on a GeoMap
Assignee: Andrei

Scenarios

Precondition:
- The user has navigated to the landing page.
Main success scenario:
- The user can see maps of other users indicated by markers
- The user can view a picture of the map by clicking on a marker
- The user can view the link to a map by clicking on the marker
- The user can navigate to the map after clicking the corresponding link (if logged in)
Alternative scenario:
Error scenario:
Postcondition:
Non-functional Constraints:

Use Case: Heatmap

Scope: Plant Layer
Level: User Goal
Actors: App User
Brief: The user gets a visual indication for good/bad spots on the map.
Assignee: Lukas (Frontend) and Christoph (Backend)

Scenarios

Precondition: The user has opened the plant layer.
Main success scenario:
- The user:
  - selects a plant or area of plants.
  - places a new plant or area of plants.
- The user gets a visual indication which places of the map are ideal, okay and not suited for the plant to be placed.
- After placement gets aborted, the visual indication disappears.
Alternative scenarios:
- The user can change opacity or hides the heatmap.
- The user changes the presence of the mouse-over information (check box).
Postcondition: None.
Note: See relation layer for which relations exist.
Environmental Constraints:

Use Case: Infrastructure Layer

Summary

Scope: Infrastructure Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move and delete infrastructure elements in their plan.
Assignee: Daniel

Scenarios

Precondition: The user has opened the app and has selected the infrastructure layer.
Main success scenario: The user successfully adds, edits, moves and deletes infrastructure elements in the infrastructure layer. Infrastructure elements are, e.g.:
- taps
- wifi spots
- water storage tanks
- irrigation systems For placement:
- positioning the elements in the appropriate locations
- adjusting their properties as needed.
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario: The user attempts to add, move or edit an infrastructure element but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The user's map includes the added, edited, moved or deleted infrastructure elements as desired.
Non-functional Constraints:
- Is an additional layer
- Performance: more than 500 elements per year should be usable without noticeable delays and acceptable memory overhead

Use Case: Landscape Layer

Summary

Scope: Landscape Layer
Level: User Goal
Actors: App User
Brief: User adds elements to their map using hand-drawn shapes or common shapes.
Assignee: Daniel

Scenarios

Precondition: User has opened the app and selected the landscape layer.
Main success scenario: User successfully adds elements to their map using hand-drawn shapes or common shapes such as circles, ellipses, squares, and rectangles. Element types include (icons from Nextcloud):
- wall
- plain
- pond
- (glas)houses
- barns
- plant beds
- circles
- doors
Alternative scenario: User accidentally adds a shape in the wrong location and uses the app's undo function to correct the mistake.
Error scenario: User attempts to add a shape but the app is experiencing technical difficulties and is unable to process the request, displaying an error message.
Postcondition: The user's map includes elements added using hand-drawn or common shapes.
Non-functional Constraints:
- Is an additional layer
- Performance: more than 200 elements per year should be usable without noticeable delays and acceptable memory overhead

Use Case: Relation Layer

Summary

Scope: Relation Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move and hide relations.
Assignee: Lukas, Stefanie

Scenarios

Precondition: The user has opened the app and has selected the relations layer.
Main success scenario:
- Relations are individual elements or connect two elements, that are removed or added when adding, moving, removing, deleting or modifying elements on the map:
  - Crop rotation
  - another plant is at the same spot in future (+-)
  - nearby companion or antagonist (+-)
  - temporal beneficial or destructive relation (+-)
  - shade mismatch (-)
  - hydrology mismatch (-)
  - plant is on unsuitable or beneficial zone (+-)
- The user successfully adds, edits, moves and hides relations.
Alternative scenario: The user accidentally adds, edits, moves or hides the wrong relations and uses the app's undo function to correct the mistake.
Error scenario:
Postcondition: The user's map shows the relations as desired, or hides all of them if the layer has visibility off.
Non-functional Constraints:
- Performance: more than 10000 elements per year and per alternative should be usable without noticeable delays and acceptable memory overhead
Note:
- it gets dynamically generated based on alternatives
- while doing drag and drop of plants, relations are shown anyway.
Environmental Constraints:
- Hydrology Layer
- Fertilization Layer

Development

relations are generated and stored in backend

Use Case: Rename Layers

Summary

Scope: Created or Alternative Layers
Level: User Goal
Actors: App User
Brief: User renames created or alternative layers
Assignee: Daniel
Simplification: No support for alternative layers

Scenarios

Precondition:
- User has opened the app and has at least one created or alternative layer.
Main success scenario: User successfully renames created or alternative layers by selecting the desired layer and entering a new name.
Alternative scenario:
- The user accidentally renames a layer to a name that is already in use and uses the app's undo function to correct the mistake.
Error scenario:
- The user attempts to rename the layer but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
- The user attempts to rename the layer to a name that is already in use and the app is unable to complete the request, displaying an error message.
- The user attempts to rename the layer by entering a name that is longer than the maximum allowed length and the app is unable to complete the request, displaying an error message.
Postcondition: The user has changed the name of the selected layer.
Non-functional Constraints:

Use Case: Shade Layer

Summary

Scope: Shade Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move, remove and delete shade areas in their map in the shade layer and adjust the intensity.
Assignee: Lukas
Simplification: we don't distinguish between Winter and Summer shade

Scenarios

Precondition: The user has opened the app and has selected the shade layer.
Main success scenario: The user successfully adds, edits, moves, removes and deletes shade areas in their map in the shade layer. This includes positioning the indicators in areas of the landscape that receive more or less sun exposure and adjusting the intensity of the shade area. Shade areas can be added by a big brush to draw on the shade layer.
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario: The user attempts to add or edit a shade area but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The user's map includes the added, edited, moved, removed or deleted shade area as desired.
Non-functional Constraints:
- is a brushing layer
- Performance: Map sizes with more than 1000 shadings in 1ha in 10000 raster elements (m²) per year should be usable without noticeable delays and acceptable memory overhead

Use Case: Zones Layer

Summary

Scope: Zones Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move, remove and delete zones in their map in the zones layer.
Assignee: Lukas

Scenarios

Precondition: The user has opened the app and has selected the zones layer.
Main success scenario: The user successfully adds, edits, moves, remove and deletes zones in their map in the zones layer. This includes positioning the zones in the appropriate location. Zones can be added via common shapes, hand drawn polygons or a big brush to draw on the zones layer. The zones exclude each other (different to e.g. animals, where they can overlap).
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario: The user attempts to add, move or edit a zone but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The user's map includes the added, edited, moved, remove or deleted zone elements as desired.
Non-functional Constraints:
- is a brushing layer
- Supports alternatives (different perspectives, e.g. guests)
- Performance: Map sizes with more than 1ha in 10000 raster elements (m²) per year should be usable without noticeable delays and acceptable memory overhead

Done Use Cases

Use Case: Area of Plants

Summary

Scope: Plants Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move and delete plant areas elements in their map in the plants layer.
Assignee: Paul

Scenarios

Precondition: The user has opened the app and has selected the plants layer.
Main success scenario:
- While adding a plant, while holding the mouse, the user can draw a rectangle.
- The size of the arena and the number of plants is shown next to the mouse.
Alternative scenario: The user accidentally drew a wrong size of the area:
- and uses the app's undo function to correct the mistake, and
- is able to change the size as wanted.
Error scenario:
- The user attempts to add, move or edit a plant area element but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
- There is an error in the app's plant relationship indication and the lines connecting the plants are not displayed correctly. In this case, the app displays an error message.
Postcondition:
- The user's map includes the added, edited, moved or deleted plant area element as desired.
- If constraints are violated for the place where a plant was added or moved, relations get added (or removed) to (from) the relation layer.
Non-functional Constraints:
- Partial offline availability: editing attributes, especially for planting and harvesting
- Supports alternatives
- Performance: more than 10000 elements per year and per alternative should be usable without noticeable delays and acceptable memory overhead (area of plants should count as one element)

Use Case: Base Layer

Summary

Scope: Base Layer
Level: User Goal
Actors: App User
Brief: User imports a picture to use as a background.
Assignee: Moritz

Scenarios

Precondition:
- User has opened the app and selected the base layer.
- The user has an orthophoto or site plan and knows the real length of a flat part of the orthophoto (e.g. length of house's roof).
Main success scenario:
- User successfully imports an orthophoto or site plan to be used as a background by selecting the option to
  - import a picture to Nextcloud or
  - by choosing an image from Nextcloud.
- The user draws a polygon telling the app where the borders of this image are (these boarders are stored in the map and not subjective to "alternatives").
- Georeferencing (of polygon): The user tells real lengths of lines (on flat land) so that we know how big this image in reality is.
- The user chooses an orientation of the picture, i.e., rotate the image to where north is.
- The user chooses where north related to the screen is by choosing the angle in degrees it should be rotated by.
Alternative scenarios:
1. User selects an (additional) alternative image.
  - The user scales the image, so that it fits to prior georeferencing.
  - The user chooses an orientation of the picture, i.e., rotate the image to where north already is to fit prior north orientation
  - The user can switch back to the original image.
2. User accidentally replaces the ortophoto with another image or wrongly put a line in the polygon and presses undo to correct the mistake.
3. The user later (after changes in other layers were already done) finds that the polygon, the orientation or the georeferencing contains a problem:
  - The app automatically saves the current version of the map.
  - The user corrects the polygon, the orientation or the georeferencing.
  - The database gets rewritten with the new geometric data. (No undo available but the user can load the previous version.)
Error scenario:
- User attempts to import a file that is not a supported image format or is corrupted and the app displays an error message. The user is prompted to choose a correct image in one of the supported formats instead.
- The orders polygon(s) do not close: the app displays an error message. The user is prompted to close the polygon(s).
Postcondition: The user's selected background image and borders are used for further planning.
Non-functional Constraints:
- Support for multiple image formats
- Supports alternatives, see Alternative scenario 1 (but alternatives is not supported for border polygon/georeferencing and Alternative scenario 3.)
- Support for undo for most changes but not for Alternative scenario 3.
Notes:
- You can read more about Nextcloud integration here.

Use Case: Entry and List of Seeds

Scope: Seed Management
Level: User Goal
Actors: App User
Brief: The users manage their seeds by adding, editing, searching, viewing and archiving them.
Assignee: Moritz

Scenarios

Precondition: The user has opened the seed management feature in the app.
Main success scenario:
- The user is able to add new seeds to their list.
- The user is able to search for seeds using the full plant name.
- The user is able to view a list of seeds where the complete name, amount, quality, harvest year, and origin is visible.
- The user is able to edit or archive seeds of the list.
- The user is able to search for seeds with their complete name.
Alternative scenario: The user accidentally archives a seed from their list and uses the undo feature to correct it.
Error scenario: There is an error when the user attempts to add or edit a seed entry with invalid data such as an invalid price. In this case, the app validates when saving the seed and shows a validation error.
Postcondition: The user's seed list corresponds exactly with the physical seeds in the user's seed box in reality.

Use Case: Grid

Summary

Scope: Grid
Level: User Goal
Actors: App User
Brief: The app will display a variable scale coordinate grid.
Status: Done
Assignee: Moritz

Scenarios

Precondition:
- User has opened the map.
Main success scenario:
- The user sees a variable scale coordinate grid with 1 meter, 10 meter and 10 centimeter spacings depending on the current map scale.
- A yard stick displays the current scale of the coordinate grid.
- The origin point is marked on the map.
- The grid can be toggled on and off using a button in the top right toolbar.
Non-functional Constraints:
- Support for changing viewport (zoom, position, etc.)
- The functionality is only available in the frontend.

Use Case: Guided Tour

Summary

Scope: Gamification
Level: User Goal
Actors: User
Brief: The user is presented with an introduction tour upon first encountering the map editor.
Status: Done
Assignee: Thorben

Scenarios

Precondition:
- The user is member and logged in.
- The user has created a map.
- The user has opened the map editor.
- The user has not previously completed the guided tour.
Main success scenario: The user is shown a guided tour, which explains the features of the map editor based on a small scenario. The user will have to place and remove plants, use the timeline, see plant relations and use the undo feature in this scenario. After completing the guided tour, the user is awarded a Blossom.
Alternative scenario: The user does not want to do the guided tour and can cancel it during any step. Upon cancel, the user decides to see it on their next visit or to cancel it indefinitely.
Error scenario: A network problem prevents the frontend from checking if the guided tour was already completed and will show an error message.
Postcondition: The guided tour is completed or canceled and won't be shown again next time.
Non-functional Constraints:

Development Progress

Tour steps and display options are defined in their own typescript file.
CSS classes for the styling of the tour were added as a separate CSS file.
Guided tour is added to the application as part of the map wrapper.
The tour is started and event listeners are added in the map component.
Follow-up Issue(s): #710.

Use Case: Landing Page

Summary

Scope: Landing Page
Level: User Goal
Actors: App User
Brief: The user can view sites/maps on a GeoMap and apply for a membership
Assignee: Paul

Scenarios

Precondition:
- The user has navigated to permaplant.net.
Main success scenario:
- The user can interact with the displayed GeoMap
- The user can apply for a membership
- The user can contact us
- The user can read imprint (Impressum)
- The user can read about privacy (Datenschutz)
- The user can read about copyright
- The user can login
Alternative scenario:
Error scenario:
Postcondition:
Non-functional Constraints:
Linked Use Cases:

Open points:

privacy/copyright missing

Use Case: Layer Visibility

Summary

Scope: All Layers
Level: User Goal
Actors: App User
Brief: User changes the visibility of layers in their map
Assignee: Samuel

Scenarios

Precondition: User has opened the app and has multiple layers available to view.
Main success scenario: User successfully changes the visibility of layers:
- visibility on/off (elements and colors on layer are fully visible or invisible)
- opacity in % (elements and colors on layer have a chosen opacity)
Error scenario: The user attempts to toggle the visibility but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The user has changed the visibility of the selected layer.
Non-functional Constraints:
improvements
Alternative scenario:
- On activation of a layer, also the visibility gets turned on.
- On activation of some layers, the visibility of others layer changes; e.g., activation of the hydrology layer also sets the visibility of the infrastructure layer to on.

Notes

The layer opacity is a Konva feature and is implemented in Map.tsx. The control elements for the opacity and visibility can be found in LayerListItem.tsx

Summary

Scope: Authentication
Level: User Goal
Actors: App User, App System
Brief: The user authenticates against Keycloak to gain access to their account.
Status: Done
Assignee: Gabriel, Samuel

Scenarios

Precondition: The user has not yet authenticated against Keycloak.
Main success scenario:
- The user enters their login credentials and Keycloak successfully authenticates them.
- Alternatively, they go to a permalink for their user or map, where no login is needed.
Alternative scenario: The user enters incorrect login credentials. In this case, the app displays an error message to the user indicating that the login failed.
Error scenario: There is an error in the app's authentication process. In this case, the app displays an error message to the user and tells them to try again.
Postcondition:
- The user is authenticated and has access to the PermaplanT app.
- The user is authenticated and has access to Nextcloud.
Non-functional Constraints:
- The login process must be secure to protect the user's personal information.
- The app must clearly communicate to the user whether the login was successful or not.

Left-Overs

Add an auth mechanism to the /api/updates/maps endpoint

Use Case: Manage Additional Layers

Summary

Scope: Additional Layers
Level: User Goal
Actors: App User
Brief: User creates, renames, ranks and removes a new additional layer
Assignee: Daniel

Scenarios

Precondition:
- User has opened the app.
Main success scenario:
- The user can create a new additional layer.
- These layers should give hints that they are not semantic for the application.
Alternative scenario:
Error scenario:
- The user attempts to create the layer but the app is experiencing technical difficulties, e.g. too many layers were already created, and is unable to complete the request, displaying an error message.
Postcondition:
- This new layer is created, will get a new subsequent number and is enabled.
Non-functional Constraints:

Use Case: Map Creation

Summary

Scope: Map Management
Level: User Goal
Actors: App User
Brief: The user creates or duplicates a map.
Assignee: Thorben

Scenarios

Precondition: The user has opened the app and is on the map management screen.
Main success scenario:
- The user successfully creates or duplicates a new map by providing:
  - a name
  - a location (where that map is)
  - a text
  - a photo from Nextcloud (of that map)
  - privacy setting: public, protected (only members), private
  - soil (sandy to clay)
- The same information can be later edited in a settings dialog.
Alternative scenario:
- The user attempts to create a map with a name that is already in use. In this case, the app displays an error message and prompts the user to choose a different name.
- The user attempts to create a private map but doesn't have the permission to do so. In this case, the app displays an error message.
Error scenario: There is an error in the map creation process and the map is not created as intended. In this case, the app displays an error message and allows the user to try again.
Postcondition: The map is successfully created.
Non-functional Constraints:

Left-Overs

Duplication of map not yet done.

Use Case: Map Deletion

Summary

Scope: Map Management
Level: User Goal
Actors: App User
Brief: The user deletes a map.
Assignee: Moritz

Scenarios

Precondition: The user has opened the app and is on the map management screen.
Main success scenario:
- The user deletes a map by selecting it from the list of maps.
- The user receives the following information:
  - a warning that the whole map including all layers will be deleted, but
  - it is possible to contact the PermaplanT service team within one month to restore the map.
- The user confirms their choice to delete the map by entering the maps name into a text field.
- Within one month, the PermaplanT service team can restore the map via provided SQL commands.
Error scenario: There is an error in the map deletion process and the map is not deleted as intended. In this case, the app displays an error message and allows the user to try again.
Postcondition: The map is deleted.
Non-functional Constraints:
Linked use cases
- Map Creation

Use Case: Map Search

Summary

Scope: Map Search
Level: User Goal
Actors: App User
Brief: The user can search for maps within the app using keywords, including the ability to search for public maps created by other users.
Assignee: Moritz

Scenarios

Precondition: The user has opened the app and is on the map search page.
Main success scenario:
- A list of all maps are shown, including both the user's own maps and public/protected maps created by other users. For each map:
  - A small image either of the photo or of its content is shown
  - The name is shown
- The user enters a keyword into the search field and the app filters the list of maps that match the keyword.
- The user can then select a map to view it.
Alternative scenario: The user enters a keyword that does not match any maps in the app. In this case, the app displays a message to the user indicating that no maps were found.
Error scenario: There is an error in the app's search functionality and the maps are not correctly retrieved. In this case, the app displays an error message to the user and allows them to try again.
Postcondition: The user has successfully searched for a map and retrieved correct results within the app.
Non-functional Constraints:
- The app's search functionality must be fast and efficient in order to provide a seamless user experience.
- The app must clearly communicate to the user whether their search was successful or not.

Use Case: Map Timeline Event View

Summary

Scope: Map View
Level: User Goal
Actors: User, App
Brief: The user sees addition/removal of elements as events using the timeline feature.
Assignee: Daniel Steinkogler

Scenarios

Precondition: The user has opened the app and selected a map.
Main success scenario:
- The user sees events represented on the scrollbar of the timeline feature, allowing them to understand how the map changed over time. Events include:
  - addition of an element to the map (colored green)
  - removal of an element from the map (colored red)
- the events are represented by a visual indication directly at the day/month/year on the sliders.
- if there is no event at a certain point in time, the graph is empty. That means that 0 events should lead to no visual indication, so that 0 and 1 can be easily distinguished.
Alternative scenario:
- The user has not yet added/removed any elements, therefore no events are visible on the timeline.
Error scenario: There is an error in the timeline display or event loading functionality. In this case, the app displays an error message and allows the user to try again.
Postcondition: The user successfully sees the events on the timeline scrollbar.
Non-functional Constraints:
- Offline availability

Use Case: Map Timeline Single Selection

Summary

Scope: Map View
Level: User Goal
Actors: App User
Brief: The user can view the map at different points in time by using the timeline feature.
Assignee: Daniel Steinkogler

Scenarios

Precondition:
- The user has opened the app and selected a map.
- The timeline shows the current date.
Main success scenario:
- A timeline is presented to the user which allows them to select year, month and day.
- Year, month and day can be individually selected by scrolling, moving sliders or clicking on the elements.
- This allows navigation to a different point in the past, present and future.
- The map updates to show the state of the garden at the selected point in time (removing or adding elements accordingly).
- Adding or removing elements is done on the selected date.
- The selected date is highlighted.
- The sliders are synchronized, i.e., if the user scrolls the day slider over the last day of the month, the month slider is updated to the next month.
Alternative scenario:
- The user corrects the dates in the attributes of elements or presses undo to undo changes in the dates.
Error scenario:
Postcondition: The user has successfully changed to the desired date.
Non-functional Constraints:
- Performance: data in up to 100 years should be fast to use
Note:
- Single Date Selection must always be an exact date so we have a well-known date (reference point) when elements got added to the map.

Use Case: Map Undo/Redo

Summary

Scope: All Layers
Level: User Goal
Actors: App User
Brief: The user can undo or redo their own actions to correct mistakes made to the map.
Status: Done
Assignee: Paul

Scenarios

Precondition: The user has made a change in the map that they want to undo.
Main success scenario:
- The user selects the undo option.
- The app successfully undoes the previous action that modified the map in some way.
Alternative scenario:
- The user used undo by accident.
- In this case, the user can press redo, to undo the undo.
Error scenario: There is an error in the app's undo/redo functionality and the action is not correctly undone or redone. In this case, the app displays an error message to the user and allows them to try again.
Postcondition: The user's action within the map has been undone or redone as desired. It may be an action in a different layer.
Non-functional Constraints:
- The app must clearly communicate to the user whether an action can be undone or redone.
- The app must clearly communicate which undo/redo action was done.
- Offline availability
- All operations changing the map or elements must support undo/redo, unless specified differently in non-functional constraint.

Left-Overs

usability improvements#657

Use Case: Measuring Distance

Summary

Scope: All Layers
Level: User Goal
Actors: User, App
Brief: The user can measure the distance between different elements in their map.
Status: Assigned
Simplification: Measuring only in frontend (not via backend as described in Non-functional Constraints)
Assignee: Moritz

Scenarios

Precondition: The user has opened the app and has selected any layer (e.g. plants).
Main success scenario:
- The user selects the "Measure Distance" button.
- The user clicks on the first point they want to measure the distance from.
- The user clicks on the multiple elements between which the user wants to create the path of the length measurement.
- The app displays the total sum of elements in one path in both units (meters, feet).
- New measurement paths can be started while keeping the previous measurements on the display.
- When status bar is closed, measurements are still displayed and the work from the previous layer can be continued.
- Once the "Measure Distance" button is pressed again, all measurements are permanently removed.
Error scenario:
- There is an error in the app's distance measurement function and the displayed distance would not be accurate. In this case, the app displays an error message and allows the user to try again.
Postcondition: No change on the elements of the map.
Non-functional Constraints:
- The app must accurately measure the distance between elements in the selected unit (based on GIS data).note
- The app must accurately measure the distance between elements in the selected unit (based on GIS data).
Notes:
- Follow up issue

Use Case: Multi-Select

Summary

Scope: All Layers, except Base
Level: User Goal
Actors: App User
Brief: The user changes properties or deletes multi-selected plants.
Assignee: Christoph N.

Scenarios

Precondition: The user has made a selection of at least two plants.
Main success scenario:
- The user sets the Added on date.
  Then he sets the Removed on date.
- The user clicks on the deletion button and sees all selected plants disappear from the map.
Alternative scenario:
- The user accidentally deletes the selected plants and uses the app's undo function to correct the mistake.
- The user accidentally sets a wrong date and uses the app's undo function to correct the mistake.
Error scenario: The app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition:
- The Added on date of all selected plants are changed.
- The Removed on date of all selected plants are changed.
- All deleted plants are gone from the map as if they never existed.
Non-functional Constraints:
- The user should be able to undo/redo setting the Added on and Removed On date of all selected plants.
- The user should be able to undo/redo the deletion of all selected plants.

Development Progress

fully done

Use Case: Plants Layer

Summary

Scope: Plants Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move, remove, and delete plant elements in their map in the plants layer.
Assignee: Paul

Scenarios

Precondition: The user has opened the app and has selected the plants layer.
Main success scenario:
- The user can search for plants or seeds.
- While the user adds a plant, constraints are shown:
  - The user is able to view the relationships between the plants. She does so by looking at the lines connecting the existing plants with a symbol around the mouse cursor indicating companion or antagonist.
- The user positions the plant element in the appropriate location in the map.
- The user is able to
  - move,
  - resize (without flipping) and rotating,
  - edit (e.g. when planted, when harvested),
  - remove (that it was removed from the map to make space on this spot for other plants on this day), and
  - delete (that it never existed) selected plants.
- The user adjusts the plant elements and their relationships as needed.
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario:
- The user attempts to add, move or edit a plant element but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
- There is an error in the app's plant relationship indication and the lines connecting the plants are not displayed correctly. In this case, the app displays an error message.
Postcondition:
- The user's map includes the added, edited, moved, removed or deleted plant element as desired.
- If constraints are violated for the place where a plant was added or moved, warnings get added (or removed) to (from) the relation layer.
Non-functional Constraints:
- Partial offline availability: editing attributes, especially for planting and harvesting
- Supports alternatives
- Performance: more than 10000 elements per year and per alternative should be usable without noticeable delays and acceptable memory overhead
- Annual plants automatically get removed after one year.

Development Progress

The user is presented with a list of seasonal plants.
Currently only seasonal seeds are shown.
The expiration date is NOT considered.
The backend part is implemented here.
The list is then shown in this component
Planting relationships are shown.
The backend part is implemented here.
The overlay is displayed from this component
Annual plants are NOT automatically removed after one year.

Use Case: Search Plants

Summary

Scope: Plants Layer
Level: User Goal
Actors: App User
Brief: The user can search for plants.
Status: In Progress
Assignee: Moritz (Frontend), Gabriel (Backend)
Test Protocol: doc/tests/protocols/plant_search.md

Scenarios

Precondition:
- The user is logged in to the app.
- The plants layer or seed entry dialog is shown.
Main success scenario:
- The user types something into the search text box.
  This will search for partial matches of actual plants (not higher ranks) in:
  - Unique name
  - German common names
  - English common names
  - Attributes that describe the plant, especially edible_uses, so that people can search for popcorn.
- The results are ranked by how well the type text matches with the plant name, e.g. the user wrote "fir", "fir" should be first hit
- The plant name is rendered as described in hierarchy description
Alternative scenario:
- No match can be found for what the user was searching for.
  A message will be displayed that nothing was found.
Error scenario:
Postcondition:
- The user has found the plant or a similar one to add to her map.
Non-functional Constraints:
- Performance
- If there is a possible match in the database, it should be included (regardless of language settings etc.)

Out-of-scope

The matched part of the text should be bold.
Results then get extended by the whole hierarchy below, e.g., a search for Tomato should include all cultivars.
We don't consider language for ranking so that the backend can be agnostic to language.

Further out-of-scope topics are documented in the closed issue #379.

Use Case: Translation

Summary

Scope: Translation
Level: User Goal
Actors: App User
Brief: The user can choose the app's interface to be in English or German.
Status: Done
Assignee: Paul

Scenarios

Precondition: The user has opened the app and wants to change the language of the interface.
Main success scenario: The user successfully translates the app's interface and text into English or German by selecting the desired language from the app's menu. By default, the app's interface language will be set to the user's browser language. If the language is neither English or German, the app's interface will default to English.
Alternative scenario: The user accidentally selects the wrong language and uses the app's translation function to correct the mistake.
Error scenario: User attempts to translate the app's interface and text but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The app's interface and text are displayed in the selected language.
Non-functional Constraints:

Developers

Read doc/guidelines/i18n.md for further information.

Use Case: Zoom

Summary

Scope: Zoom
Level: User Goal
Actors: App User
Brief: The user can zoom in and out on their landscape map to view details more clearly or get a better overview of their map.
Status: Done

Scenarios

Precondition: The user has opened the app and has selected the desired layer (e.g. plants, paths).
Main success scenario: The user is able:
- to set a scaling factor,
- to zoom in on a specific area down to 10x10cm (lowest resolution), and
- to zoom out to view a wider area up to 1000mx1000m.
Alternative scenario: The user accidentally zooms in or out too far and uses the "Zoom Reset" button to return to the default zoom level.
Error scenario: There is an error in the app's zoom functionality and the map is not displayed correctly at the selected zoom level. In this case, the app displays an error message and allows the user to try again.
Postcondition: The user has zoomed in or out on their map as desired.
Non-functional Constraints:
- The app must accurately measure the distance between elements in the selected unit.
- Offline availability (if zoom is within the range of previously used zoom anywhere on the map)

Draft Use Cases

Use Case: Add Plant Relationships

Summary

Scope: Plants Layer
Level: User Goal
Actors: App User
Brief: A new plant relationship is added to the system.

Scenarios

Precondition:
- The user has opened the UI to propose a new relationship.
Main success scenario:
- Details about the relationship are provided by the user.
  - The two sides of the relationship can be
    - Specific plants
    - Taxonomic ranks which are not specific plants
  - The type of the relationship can be
    - Companion
    - Antagonist
    - Neutral
  - Notes providing information on the why's and how's.
Alternative scenario:
- The user creates a relationship which is only effective for one or more of her selected maps.
  In this case there is no review process. Map-specific relationships take precedence.
Error scenario:
- The user tries to add a global relationship where another global with identical sides already exits.
  The user is informed about this and can't create the relationship.
- The user tries to add a map-specific relationship where another map-specific with identical sides already exits.
  The user is informed about this and can't create the relationship.
Postcondition:
- A new relationship between plants is reviewable by other users.
- A new relationship between plants is considered when suggesting alternatives.
Non-functional Constraints:

Use Case: Contributing Member

Summary

Scope: Membership
Level: User Goal
Actors: App User
Brief: The user receives a membership without compensation via money through contributions.

Scenarios

Precondition:
- The user already has an existing membership OR
- The user has currently no membership.
Main success scenario:
- The user can receive permacoins through various activities in the app, like:
  - gaining Blossoms in the Expert Track.
  - getting likes from other users on their reviews.
  - getting approvals on their submitted plant relationships.
  - getting their comments on a map marked as helpful by the maps owner.
  - recruiting new members.
- The user can see their exact count of current and previous permacoins in their profile.
- If the user applied for the contributing membership and when reaching a certain milestone with the amount of gathered permacoins, the user will be given the current calendar year of membership without compensation via money.
- Permacoins can not be transferred from the current into another year nor be exchanged to money in any way.
Alternative scenario:
- The user does not gather enough permacoins and has to pay the full price for this years membership.
Error scenario:
Postcondition:
- The user has the permission to use the app and to be part of the community.
Non-functional Constraints:

Use Case: Diff

Summary

Scope: All Layers, except Base
Level: User Goal
Actors: User, App
Brief: The user can visualize differences between two dates.

Scenarios

Precondition: The user has opened the app and has selected the desired layer (e.g. plants).
Main success scenario:
- The user clicks on the first date in the timeline.
- The user double clicks on the second date in the timeline.
- Plants that were added or removed between these dates are marked visually.
Alternative scenario:
- If no differences are available, a message is displayed.
Error scenario:
- There is an error in the app's difference calculation. In this case, the app displays an error message and allows the user to try again.
Postcondition:
- Unless the user clicks on the timeline again, the user cannot add or remove plants.
Non-functional Constraints:
- None.

Use Case: Dimensioning Layer

Summary

Scope: Dimensioning Layer
Level: User Goal
Actors: App User
Brief: The user can put dimensioning between elements.

Scenarios

Precondition: The user has opened the app and has selected the dimensioning layer.
Main success scenario:
- The user selects elements.
- A line with arrows at the end and the distance in the middle gets added to the dimensioning layer.
Alternative scenario:
- The user accidentally clicks on the wrong element and can remove the dimensioning.
Error scenario:
- There is an error in the app's distance measurement function and the displayed distance would not be accurate. In this case, the app displays an error message and allows the user to try again.
Postcondition: Dimensions are added.
Non-functional Constraints:
- Is an additional layer
- Must be printable.
- New Layers can be created.
- Performance: at least 100 elements per year should be usable without noticeable delays and acceptable memory overhead

Use Case: Diversity Score

Summary

Scope: Diversity Score
Level: User Goal
Actors: App User
Brief: A users map gets a diversity score depending on his usage of diversity and polyculture.

Scenarios

Precondition:
- The user has opened the app and is editing a map.
Main success scenario:
- The user drags and drops various plants onto his map.
- The system calculates a diversity score after each plant operation based on how diverse the map is.
- Plants beneficial to the ecosystem (e.g. they are not problematic or provide food and shelter for wild life) or having many different plants increase the score, while overusing a small set of plants (in relation to size of map) negatively affects the scoring.
- The user will be motivated to increase the diversity score and therefore optimizes the diversity and usage of polycultures on the map.
Alternative scenario:
Error scenario:
- The app incorrectly calculates the diversity score. In this case the app will re-calculate the score after the next operation the user makes while the score is visible.
Postcondition:
- The user finds the diversity score in the map overview and the map planner.
- The diversity score affects the order of the results in the map search.
Non-functional Constraints:-
- Performance

Use Case: Event Notification

Summary

Scope: Notifications
Level: User Goal
Actors:
- Host: App User that hosts the event
- Nearby user: App User that is nearby the host
- User without location: App User that has no location

Scenarios

Precondition:
- The host has opened the app and is logged in.
- The host and the nearby user are located nearby (requires location settings of both users, nearby is a defined radius).
Main success scenario:
- The host announces an event (e.g. a "virtual welcome party" because planning of the map was finished)
Alternative scenario:
Error scenario: The host does not have a location set: An error message is displayed, which informs them that the location is required for sending invitations.
Postcondition:
- Nearby user gets a notification which informs them about the event (e.g. invitation to visit the map virtually).
- The user without location gets a notification which informs them about the event (e.g. invitation to visit the map virtually) with the additional text that they get the invitation because they don't have a location set.
Non-functional Constraints:

Use Case: Experimental Results

Summary

Scope: Experimental Results
Level: User Goal
Actors: App User
Brief: The user can give a feedback of the actual results for a map in a measuring cycle.

Scenarios

Precondition:
- The user has opened the app.
- The user has previously fully designed a map and implemented it in real life.
Main success scenario:
- The user gets a number of simple recommended methods to measure amount and quality of their harvest, including a step-to-step guide to execute them.
- The user performs one or more of these methods or conducts their own advanced analysis.
- The user can input the results of the analysis in a feedback form of the map.
- The data gets saved and is used to adapt the parameters of the used entities in this map.
Alternative scenario:
Error scenario: A technical error occurs, preventing the user from submitting the feedback form. In this case the system should display an error message and allow the user to try again.
Postcondition: The accumulated data from this and previous measuring cycles can be viewed as a report in a separate details screen of the map.
Non-functional Constraints:

Use Case: Gain Blossoms

Summary

Scope: Gain Blossoms
Level: User Goal
Actors: App User
Brief: The user is awarded with Blossoms for achieving certain milestones.

Scenarios

Precondition:
- The user has opened the app and uses it.
Main success scenario:
- The user can see a list of incomplete milestones and their respective requirements. An user can reach a certain milestone by e.g.:
  - change layers (visibility etc.)
  - base layer: set base image
  - change the date.
  - planting their first plant.
  - using an element from a new layer for the first time.
  - harvesting a plant for the first time.
  - opening their first map for collaboration.
  - collaborating on a map from another user for the first time.
- Blossoms are grouped in different tracks by what goal they try to incentivize, e.g.:
  - Beginners Track: leading new users through the basic features of PermaplanT.
  - Seasonal Track: motivate users to completely plan out their map and keep it updated through the seasons.
  - Completionist Track: rewarding users for enriching their own data with the results of their harvest.
  - Expert Track: incentivize users to support the platform and its other users to gain a free membership.
- Further ideas:
  - planting their first full group of companions.
  - planting their first recommended diversity plant.
  - submitting updated plant data.
  - updating their plant relations with data from the harvest for the first time.
  - reaching a specific diversity score goal.
  - gathering all ingredients for an ingredient list for the first time.
  - buying their first batch of seeds.
  - creating their first event.
  - honoring a map from another user for the first time.
  - posting their first comment on a map from another user.
  - writing their first review of a map from another user.
  - receiving their first honor from another user.
  - receiving their first review from another user.
  - having their first conversation with another user through matchmaking.
  - adding their first new plant in the apps database.
  - adding their first new seed in the apps database.
- Progress of the individual milestones is tracked independently and they can be accomplished in any order.
- The user is being kept updated on their progress when pursuing actions to complete a milestone.
- Upon completing a milestone, the user is informed of their achievement and is awarded the corresponding Blossom.
- Some Blossoms reset after a year to engage the user to continue the work in following seasons.
Alternative scenario:
Error scenario: The user meets the criteria for a certain Blossom, but it will not be awarded due to an error in the app. The Blossom will be awarded the next time its criteria will be checked.
Postcondition: The awarded Blossoms will be shown in the users profile with a number indicating the amount of times this blossom was earned in previous seasons.
Non-functional Constraints:

Development Progress

Backend API call for adding a Blossom to a user is implemented in backend/src/controller/blossoms.rs.
Current version does not reference pre-defined Blossom entities as there is currently no way to add them.
Frontend awards Blossoms currently only for completing the Guided Tour.

Use Case: Habitats Layer

Summary

Scope: Habitats Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move, removed and delete habitats of animals to support their plants and ecosystem in their map in the habitats layer.

Scenarios

Precondition: The user has opened the app and has selected the habitats layer.
Main success scenario:
- The user successfully adds, edits, moves, removes and deletes aids in their map in the habitats layer. For example: nesting aids, heaps of stones or leaves, perches etc. This includes positioning the aids in the appropriate location.
- Habitats from deers and domesticated animals (like ducks and chicken) can be added by a big brush to draw on the habitats layer.
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario: The user attempts to add, move or edit an aid but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The user's map includes the added, edited, moved, removed or deleted habitats as desired.
Non-functional Constraints:
- Performance: Map sizes with more than 1ha in 10000 raster elements (m²) and more than 500 elements per year should be usable without noticeable delays and acceptable memory overhead

Use Case: Import and Export Maps

Summary

Scope: Map View
Level: User Goal
Actors: App User
Brief: Users can import and export maps.

Scenarios

Precondition:
The user has opened the app.
The user is viewing the map interface.
Main success scenario:
The user exports the current map data in the app to a GIS map file upon which the app generates a GIS map file containing the map data, which can then be shared or used in other mapping applications. The state of the map before the import is still available as a previous version.
The user imports a GIS map file by providing the required file. Once imported, the map data is displayed in the app's map view, allowing the user to interact with the imported map elements.
Alternative scenario:
The user imports a GIS map file that contains additional information that cannot be mapped to the database. The app provides a warning message because it will discard this information.
Error scenario:
In the case of errors, the original map stays unmodified:
The user attempts to import an unsupported file format or a corrupted GIS map file.
The user imports a large GIS map file that exceeds the app's size limit or takes too long to process.
The user exports a GIS map file, but the app detects that the map contains incomplete or inconsistent data.
Postconition:
The user has successfully imported or exported a GIS map file, enabling him to work with the map data in the app or share it with others.
Non-functional Constrains:
The import and export processes should be efficient and have minimal impact on the app's performance.
The app should support common GIS map file formats for maximum interoperability with other mapping applications.
The import and export options should be easily accessible and intuitive for users to understand and use.

Use Case: Ingredient Lists

Summary

Scope: Ingredient Lists
Level: User Goal
Actors: App User
Brief: The user can create lists to keep track of ingredients needed over the year.

Scenarios

Precondition:
- The user has opened the app and is editing a map.
Main success scenario:
- The user has a list of fruits and vegetables that are needed continuously over the course of a timespan, e.g. a daily smoothie or salad.
- The user inputs the items into a form in the map editor and can set a name and picture for the ingredient list.
- The user is able to have multiple of those ingredient lists.
- The lists will display what ingredients are available on the map and which still need to be planted by the user.
- While harvesting or after harvesting (if the user has conserved some of it, e.g., stored fresh fruits, dried herbs), (s)he can mark ingredients as available over a specific timespan and unmark it once the harvest is over or storage is exhausted.
- The user is awarded a Blossom for having all necessary ingredients for any list in any month and additional ones for every subsequent month the list requirements are completely met.
Alternative scenario:
Error scenario: The app does not mark a list item as (partially) harvested even though the user marked the relevant plant as harvested. In this case, the user should try again to mark the plant as harvested to re-initialize the ingredient list check.
Postcondition: The user can keep track of needed ingredients and gets an overview of plants to plant on the map.
Non-functional Constraints:

Use Case: Landing Page News

Summary

Scope: Landing Page
Level: User Goal
Actors: App User
Brief: The user can read news written in a Nextcloud chat component
Assignee: Samuel

Scenarios

Precondition:
- The user has navigated to permaplant.net.
Main success scenario: The chat should look very similar to Nextcloud chat:
- highlight items when hovering
- group by date, show exact time (not 5 min ago) Logged in users can:
- give reactions to posts Chat features (in order of importance)
1. show images
2. text should be mark/copyable
3. emoji
4. reactions
5. files
6. reply
7. directly share photo (take photo with phone)
8. remove msg/reaction
Alternative scenario:
- The user can subscribe the same content (chat) as RSS feed
Error scenario:
Postcondition:
Non-functional Constraints:
Extends Use Case:
- Landing Page

Use Case: Layer Alternatives

Summary

Scope: All Layers
Level: User Goal
Actors: App User
Brief: User selects and modifies alternatives of a layer

Scenarios

Precondition: User has opened the app and a map.
Main success scenario:
- User chooses a layer to enable
- User duplicates the layer
- User gives the layer a name
- User modifies the layer
- User may select another alternative of the layer. This change doesn't affect layer selections of other users (that work on the same map).
Alternative scenario:
- User accidentally duplicates the layer and deletes the duplicate with "delete layer" functionality
- User accidentally selects a wrong alternative as the current layer and undoes the action by selecting the correct layer
Error scenario:
- If the user encounters technical issues or errors while using the layer alternatives, the platform should display an error message and allows the user to try again.
Postcondition: The user has successfully modified and selected an alternative of a layer.
Non-functional Constraints:
- Performance: up to 10 alternatives should be fast to use
- Offline functionality depending on the layer
Note:
- Layers that support alternatives, have this specified as non-functional constraint.

Use Case: Map Honors

Summary

Scope: Map Honors
Level: User Goal
Actors: App User
Brief: The users can give an honor to the whole map of another user they visit.

Scenarios

Precondition:
- The user has opened the app.
- The user is currently viewing the map of another user.
Main success scenario:
- The user wants to show appreciation for the entirety of the currently visited map.
- The user uses the honor button to give an honor directly to the entire map.
- The amount of honors for that specific map increases.
Alternative scenario:
- The user uses the honor button to withdraw a previously given honor on the currently visited map.
- The amount of honors for that specific map decreases.
Error scenario: A network error occurs, preventing the app from updating the honor count of the given map. In this case, a warning message stating the error should be displayed and the user is prompted to try again.
Postcondition: Users can find the honor count next to the map in every instance of map selection as well as in the details screen of the map. The amount of honors affects the order of the results in the map search.
Non-functional Constraints:

Use Case: Map-Specific Favorite Groups

Summary

Scope: Plants Layer
Level: User Goal
Actors: App User
Brief: The user changes a set of favorite plant groups per map.

Scenarios

Precondition:
- The user is logged in to the app.
- The plants layer is selected.
- At least one plant is placed.
Main success scenario:
- The user adds a plant or a plant group to her list of favorites.
Alternative scenario:
- The user wants to reorder their list of favorite plant groups.
- The user wants to remove favorite plant groups.
Error scenario:
- The user attempts to add a plant group that is already in their favorites.
- The user attempts to remove a group that is not in the favorites.
Postcondition:
- The set of map-specific favorites has changed according to the changes the user made.
  The state of these favorites can be seen in the plants layer.
Non-functional Constraints:
- It must be clear that a favorite was added or removed.

Use Case: Map Statistics

Summary

Scope: Map Statistics
Level: User Goal
Actors: App User
Brief: The user can view statistics about their garden and plants.

Scenarios

Precondition: The user has opened the app and has opened their map.
Main success scenario: The user views statistics about their garden and plants. Examples of statistics include:
- Total number of plants in the garden
- Number of elements in each layer
- Total number of visits to the garden
Alternative scenario:
Error scenario:
- If the user encounters technical issues or errors while using the statistics, the platform should display an error message and allow the user to try again.
Postcondition: The user has successfully viewed statistics about their garden and plants.
Non-functional Constraints:
Alternatives (statistics depend on which alternative layers are selected)

Use Case: Matchmaking

Summary

Scope: Matchmaking
Level: User Goal
Actors: App User
Brief: The users can find other gardening enthusiasts to establish a gardening partnership.

Scenarios

Precondition: The user has opened the app and is on the matchmaking page.
Main success scenario:
- The user creates a profile that includes their gardening preferences and experience.
- The user searches for other gardening enthusiasts.
- The user sends a request to potential gardening partners to discuss their gardening partnership.
- The user and their potential gardening partner successfully establish a gardening partnership.
Alternative scenario:
- If the user is not satisfied with the results of their search, they can adjust their search parameters and try again.
Error scenario:
- If the user encounters technical issues or errors while using the matchmaking, the platform should display an error message and allow the user to try again.
Postcondition: The user has successfully found gardening partners through the app and has established a successful gardening partnership.
Non-functional Constraints:
- The matchmaking should also protect user privacy and data, including user profiles and messaging history.

Use Case: Membership Application

Summary

Scope: Membership
Level: User Goal
Actors: User (Membership Applicant), Administrator (Chairman)
Brief: The user can apply for a membership (account)
Assignee: Ready to be assigned

Scenarios

Precondition: The user has opened the app and is not logged in.
Main success scenario:
1. The user can click an register button which leads them to Keycloak to fill out:
  - username
  - first+last name
  - email address
  - birthday
  - biography
2. The user can look at public maps (read-only and without seeing addresses!)
3. The user apply for membership, with several steps:
  1. Which kind of membership is selected on landing page and "Apply for membership" clicked. Can also be clicked without being registered before, then Step 1. of Main success scenario needs to be done.
  2. form page 1
    - salutation (Anrede)
    - title (Title) (optional)
    - billing address (Rechnungsadresse)
    - country (Land)
    - additional emails (E-Mails) (optional)
    - telephone number (optional)
    - website (optional)
    - organisation (optional)
    - permaculture experience (optional)
    - user photo (uploaded and also used in Nextcloud)
  3. form page 2
    - if billing address or someone else's address should be used
    - one or several photos of the site
    - description of the site
    - location of map(s) (not shown to default-roles-permaplant users)
  4. form page 3
    - owner (KontoinhaberIn)
    - IBAN
    - BIC
    - how did you get to know about PermaplanT (optional text)
    - username for who recruited (angeworben) (optional)
    - privacy
4. An admin:
  - removes the bank account data
  - assigns the "member" role in Keycloak
  - changes quota in Nextcloud
5. The user gets a notification via email
Alternative scenario:
Error scenario:
Postcondition:
- The user can enjoy all of PermaplanT's features.
Non-functional Constraints:

Use Case: New Plant

Summary

Scope: New Plants
Level: User Goal
Actors: App User
Brief: User adds a new plant to the app's database.
Status: Needs Clarification (permapeople.org import/sync)

Scenarios

Precondition: User has opened the app and selected the "New Plants" mode.
Main success scenario: User successfully adds a new plant to the app's database by providing photos and general information about the plant.
Alternative scenario:
Error scenario:
- Input is invalid: The user is requested to correct the input.
Postcondition: Plant was added to database.
Non-functional Constraints:

Use Case: Offline

Summary

Scope: Notifications
Level: User Goal
Actors:
- User: A user who wants to work offline. Must have the permissions to lock.
- Other user: Other users who have write access to the same layers in the map
- Owner of the map.
Brief: The user has some features offline while being in the garden without Internet access.

Scenarios

Precondition:
- The user has opened the app and is logged in.
Main success scenario:
- The user presses an "offline" button. (1)
- Then the browser actually can be taken offline. (2)
- The user goes to the garden.
- The map can be edited on the layers that are marked suitable for offline functionality.
- The user comes back from the garden.
- After the work, the browser gets online. (3)
- The user presses the "offline" button again. (4)
Alternative scenario:
- After a 8h timeout or if the owner of the map decides, the lock can be removed. In this case, all data from the offline work is lost.
Error scenario: Could not go offline or online: An error message is displayed.
Postcondition:
- All changes while being online are transferred.
Non-functional Constraints: It is clearly visible in which state the browser is:
1. before going offline (browser is online)
2. offline
3. prepared for going online again (browser is online)
4. online

Use Case: Paths Layer

Summary

Scope: Paths Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move, remove and delete a connected network of paths and fences in their map in the paths layer.

Scenarios

Precondition: The user has opened the app and has selected the paths layer.
Main success scenario: The user successfully adds, edits, moves, removes and deletes a connected network of paths and fences in their map in the paths layer with:
- the chosen path thickness (small way, ... large road)
- the chosen type (stepping stones, wood chips, gravel, sealed) This includes positioning the connected network of paths and fences in the appropriate location.
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario: The user attempts to add, move or edit a connected network of paths and fences but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The user's map includes the added, edited, moved, removed or deleted connected network of paths and fences as desired.
Non-functional Constraints:
- Is an additional layer
- Performance: more than 100 elements per year should be usable without noticeable delays and acceptable memory overhead

Use Case: Plant Lore

Summary

Scope: Plant Lore
Level: User Goal
Actors: App User
Brief: The user gets shown information of plants recommended for diversity.

Scenarios

Precondition:
- The user has opened the app and is editing a map.
Main success scenario:
- The user hovers over the for diversity recommended plant.
- The user is shown a little box with additional information and interesting facts about that plant.
- The user is interested in the plant and places it on the map.
Alternative scenario:
Error scenario: The app incorrectly displays the info box on the recommended plant. In this case, the user should retry hovering over the plant to display the info box.
Postcondition:
Non-functional Constraints:

Use Case: Review Plant

Summary

Scope: Review Plant
Level: User Goal
Actors: App User
Brief: User reviews a plant information and submits form with corrections of the plant's information.

Scenarios

Precondition:
- User has opened the app and opened the plant's page.
Main success scenario:
- User reviews the plant's page and submits a form with corrections of the plant's information.
Alternative scenario:
Error scenario:
- If the user encounters technical issues or errors while using the plant review, the platform should display an error message and allow the user to try again.
Postcondition: The user has successfully reviewed the plant's information and submitted additional information.
Non-functional Constraints:

Use Case: Review Plant Relationships

Summary

Scope: Plants Layer
Level: User Goal
Actors: Reviewing User, Reviewed User, Administrator
Brief: The quality of a user-created plant relationship is assessed by others.

Scenarios

Precondition:
- The reviewing user is logged into the app.
- She is looking at a plant relationship created by another user, the reviewed user.
Main success scenario:
- The reviewing user comments on the relationship to note something that seems relevant to her.
- The reviewing user approves the relationship because she agrees with it.
Alternative scenario:
- The reviewing user only comments on the relationship but doesn't approve it and might suggest a different relationship (e.g. neutral).
- No changes are made to the relationships confidence score.
- One administrator decides on the outcome.
Error scenario:
Postcondition:
- The number of approvals are counted for the administrator to decide on the confidence score. Relationships with higher confidence score will have a higher weight when suggesting plants or suggesting alternatives.
- On changes of the confidence score, the reviewed user gets notified about the updated score.
Non-functional Constraints:

Use Case: Reward Preview

Summary

Scope: Reward Preview
Level: User Goal
Actors: App User
Brief: A user can see a preview of future rewards for his efforts.

Scenarios

Precondition:
- The user has opened the app and is editing a map.
- The user has planted at least one plant on his map.
Main success scenario:
- When viewing the map on such a date, the plants with an active blooming or harvesting period at that time will be marked on the map.
Alternative scenario:
- Optionally, this can be disabled in the users' preferences.
Error scenario: The app incorrectly displays a plant as having an active blooming or harvesting period or does not display it for a plant that should have one. In this case the user should reload the layer to let the system recalculate the conditions for displaying active blooming or harvesting periods.
Postcondition: The user always sees what personal benefits he gets from the plants on the map.
Non-functional Constraints:

Use Case: Terrain Layer

Summary

Scope: Terrain Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move and delete terrain levels in the terrain layer.

Scenarios

Precondition: The user has opened the app and has selected the terrain layer.
Main success scenario:
- The user successfully sets the base level value for the terrain layer.
- The user successfully adds, edits, moves and deletes terrain elements in the terrain layer. Terrain elements are, e.g.:
  - Hill: A hill is a terrain element that is higher than the base level.
  - Valley: A valley is a terrain element that is lower than the base level.
- Terrain elements can be drawn using brushes of different sizes.
- The height of the terrain elements should be represented by a color gradient.
Alternative scenario: The user accidentally adds or edits an terrain element in the wrong location and uses the app's undo function to correct the mistake.
Error scenario: The user attempts to add, move or edit an terrain element but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The user's map includes the added, edited, moved or deleted terrain elements as desired.
Non-functional Constraints:
- Performance: Map sizes with more than 1ha in 10000 raster elements (m²) per year should be usable without noticeable delays and acceptable memory overhead

Use Case: Todo Layer

Summary

Scope: Todo Layer
Level: User Goal
Actors: App User
Brief: The user adds todos to their map to remember what to do at certain locations
Assignee: Samuel

Scenarios

Precondition: The user has opened the app and selected the todo layer.
Main success scenario: The users successfully adds a task to their map with following content:
- location on the map
- title of card
- description
- end date
- assigned person The task is displayed on the map and can be moved, edited, archived or removed at any time.
Alternative scenario:
- The user accidentally adds a task in the wrong location and uses the app's undo function to correct the mistake.
- The user has no Board or List configured where cards should be added.
Error scenario: The user tries to add a task with a title of than 255 characters and the app prevents it by stopping any further insertions into the task input field.
Postcondition: The user's map includes tasks as desired. The tasks are synchronized to the Nextcloud Deck named after the PermaplanT map.
Non-functional Constraints:
- Offline availability
- Performance: more than 1000 elements per year and per layer should be usable without noticeable delays and acceptable memory overhead

Use Case: Trees Layer

Summary

Scope: Trees Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move, remove and delete forests, trees and, hedge bushes in their map.
Simplification: For first version it is identical to the plants layer (so any plants can be planted)

Scenarios

Precondition: The user has opened the app and has selected the trees layer.
Main success scenario: The user successfully adds, edits, moves, removes and deletes forests, trees and, hedge bushes in their map in the trees layer. This includes:
- positioning the stems (visible brown circle),
- sketching the shape (transparent green, also allows other stems and plants shine through),
- adjusting the height, and specifying the type of tree or bush.
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario: The user attempts to add or edit forests, trees and, hedge bushes but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The user's map includes the added, edited, moved, removed or deleted forests, trees and, hedge bushes as desired.
Non-functional Constraints:
- Supports alternatives
- Performance: more than 500 elements per year and alternative should be usable without noticeable delays and acceptable memory overhead

Use Case: Winds Layer

Summary

Scope: Wind Layer
Level: User Goal
Actors: App User
Brief: The user can add, edit, move, remove and delete wind orientation and areas in their map using the wind layer.

Scenarios

Precondition: The user has opened the app and has selected the winds layer.
Main success scenario:
- The user successfully adds, edits, moves, remove and deletes wind areas in their map using the wind layer.
- This includes positioning the areas in areas of the landscape that are more windy and adjusting the strength of the wind.
- Wind areas can be added by a big brush to draw on the wind layer.
- Main wind orientation can be indicated via an arrow.
Alternative scenario:
- The user accidentally edits, moves or removes an element and uses undo to correct the mistake.
- The user accidentally adds an element and deletes it with the "delete" or "undo" functionality.
Error scenario: The user attempts to add or edit a wind area but the app is experiencing technical difficulties and is unable to complete the request, displaying an error message.
Postcondition: The user's map includes the added, edited, moved, removed or deleted wind areas as desired.
Non-functional Constraints:
- Performance: Map sizes with more than 1ha in 100 raster elements (in 1a=100m²) per year should be usable without noticeable delays and acceptable memory overhead

Later Use Cases

Use Case: Calendar

Summary

Scope: Calendar
Level: User Goal
Actors: App User
Brief: The user sees which of the planned plants are to be planted next. ("Saisonübersicht")
Assignee: Samuel

Scenarios

Precondition: The user has opened the app and is on the calendar page.
Main success scenario:
- The user gets an overview when planned plants are to be raised or planted; and later to be harvested.
- It is shown in bars, ordered by next steps to be done first.
- The users move the bar according to their wishes to indicate raising or planting earlier/later.
- The users can also precisely edit the raising/planting/harvesting date as wanted by clicking on the bar.
Alternative scenario:
- The user doesn't have any planned plants yet, the page stays empty. The users are informed that they need to plan plants first.
- The bar was moved too early or too late, the users get a warning which they need to confirm. If not confirmed, the bar stays unmodified.
Error scenario:
Postcondition:
- Calendar is synchronized to Nextcloud
Non-functional Constraints:
- Alternatives (dates depend on which alternative plants layer is selected)

Use Case: Nextcloud Circles

Summary

Scope: Nextcloud integrations
Level: User Goal
Actors: App User
Brief: The user can communicate with members of shared maps.
Assignee: Samuel

Scenarios

Precondition: The user has opened the app and navigated to a map where they are a member of.
Main success scenario: The user can open the chat window and communicate with all the members of the map.
Alternative scenario:
- The user has opened a map where they are not a member of. They are able to interact with the chat only if visitors are allowed.
Error scenario:
Postcondition: The conversations are persisted in Nextcloud. For each map there is a corresponding circle created in Nextcloud. The chats of the maps are visible under circles in Nextcloud.
Non-functional Constraints:

Use Case: Visitor chat

Summary

Scope: Map View
Level: User Goal
Actors:
- Owner: App User who owns the map
- Visitor: App User who visits the map
Brief: The user can interact with a visitor chat.
Assignee: Samuel

Scenarios

Preconditions:
- The visitor has opened the app and selected a map.
- The visitor is logged in.
Main success scenario:
- The visitor is automatically greeted by the chat.
- The visitor can interact with the owner and other current visitors via the chat.
- The owner can view the chat and interact with all visitors.
- The visitor leaves the chat.
Alternative scenario:
- The owner marks a comment as helpful. The author of the comment gets points for the free membership.
Error scenario:
Postcondition: The chat is synchronized to Nextcloud
Non-functional Constraints: