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:
- Goals and Use Cases (Chapter)
- Constraints
- Context
- Solution Strategy
- Building Block View
- Runtime View
- Deployment
- Crosscutting Concepts Guidelines (Chapter)
- Architectural Decisions (Chapter
- Quality
- Risks and technical debt
- Glossary
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:
- what makes sense according to known and easily measurable natural constraints
- is practical for the gardener
- 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.
- Base1 (import photo or site plan as base image, define borders, scale, orientation)
- Terrain
- Landscape1 (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)
- Plants1 (taxa, individual and fields of plants)
- Warnings1
- 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)
1 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 likereact-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 backendcomponents/
: 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.
(only within the
dev
branch 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.
- Application should stay usable with 10.000 elements.
- 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
- copyright on plant data
Mitigation: asked for permissions
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.
- 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
Biology
- taxonomy:
A scientific classification of plants into a hierarchy. The hierarchy we use is described here. As first introduction read: - 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
- plantings (German "Pflanzung" or also "Pflanzen" depending on context):
Plants that are already positioned on the map. - row:
A row is a series of the same plantings. - area of plantings:
Are several rows next to each other, which have a specific distance to each other (row spacing).
Plantings Attributes
- width (German: Breite):
X-value of plantings and area of plantings (without rotation). - length (German: Länge):
- Is the Y-value for area of plantings (without rotation).
- Is not used for plantings (because we use width instead).
- height:
- Currently unused Z-value of plants and plantings.
- spacing (Pflanzabstand)
- row spacing (Reihenabstand)
- life cycle:
is a list containing any combination of its 3 possible values (annual, biennial, perennial) or just an empty list in case a plant has no life cycle value in the database
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).
- The API endpoints that can be called in the backend.
- 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 databaseBIND_ADDRESS_HOST
defines the host on which the server will run onBIND_ADDRESS_PORT
defines the port on which the server will run onAUTH_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 inRUST_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
- run
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 code401 Unauthorized
.
- Enter the URL http://localhost:8080/api/config and execute the request.
- Click the
Authorization
tab and selectOAuth 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
tolocalhost
. - 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
.
- Chose
- 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.
- Production:
-
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
into[profile.bench] debug = true
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 thesrc
directory. -
Copy the
schema.rs
file toschema_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 thediesel.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 createup.sql
anddown.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 fromup.sql
-
Run the migration
make migration
During development you can runmake migration-redo
to rundown.sql
andup.sql
of the most recent migration -
Add new field to Entity
e.g. extend thePlants
entity in entity.rs -
(Optional) Update the schema patch
If you see an error message similar toerror applying hunk #2
, you will have to update schema.patch -
Add field to DTOs (where applicable)
e.g. extendPlantsSummaryDto
in dto.rs -
Update usages and trait implementations of DTOs (where applicable)
e.g. implementation of theFrom
Trait forPlantsSummaryDto
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
- Added Meeting Agenda&Notes for 05.08.2024 9:00 (Markus Raab, Andrei)
- Added Meeting Agenda&Notes for 12.08.2024 9:00 (Markus Raab, Jannis)
- Added Meeting Agenda&Notes for 19.08.2024 9:00 (Markus Raab, Christoph)
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- CI: Jenkinsfile refactoring (Filip Markovic)
- ()
- ()
- ()
- ()
- ()
- ()
- Fix map delete button title attribute. (Christoph Schreiner)
- Mark WIP migrations and update release documentation (Christoph Schreiner)
- Created manual test report for dev (Stefanie Feldmann, Christoph Schreiner)
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- CI: added new changelog for 0.4.2 (Filip Markovic)
- Created manual test report for master (Stefanie Feldmann)
- Add correct links to README and add links to PermplanT (Filip Markovic)
- ()
- CI: fix dev e2e and import scraper data (Filip Markovic)
- ()
- ()
- Handle UpdateDrawingNotes in frontend and rename actions. (Jannis Adamek)
- ()
- Extend documentation for WaterRequirement, remove SoilWaterRetention (Jannis Adamek)
- ()
- ()
- Remove duplicate changelog entries (Filip Markovic)
- ()
- ()
- Implement map deletion (Moritz Schalk)
- Document frontend testing strategy (Moritz Schalk)
- ()
- 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)
- ()
- 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)
- ()
- ()
- ()
- Rename plant relations to spatial relations (Lukas Anton Lakits)
- ()
- Remove permanent deep shade from frontend & backend (Lukas Anton Lakits)
- Add width to left toolbar for all plants (Lukas Anton Lakits)
- CI: fix changelog check for dev (Filip Markovic)
- CI: add automatic scraper data to master and prod (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)
- ()
- ()
- ()
- ()
- ()
- ()
- Improve performance of heatmap algorithm (Christoph Schreiner)
- ()
- Enable map deletion (Moritz)
- ()
- Fix E2E test failure caused by changed username input label (Christoph Schreiner)
- Fix heatmap to use colors from database settings table. (Christoph Schreiner)
- ()
- ()
- ()
- CI: add db reset and e2e tests to dev (Filip Markovic)
- ()
- ()
- Refactor selection of elements (Daniel Steinkogler)
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- ()
- Add demo brush implementation (Daniel Steinkogler)
- Add notes to shadings same as plantings and drawings (Jannis Adamek)
- ()
- ()
- Updated cursor on opacity slider hover (Stefanie Feldmann)
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
todrawings
to matchplantings
. #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)
- CI: show prettier git log for (dev|master|mr).permaplant.net/version (Filip Markovic)
- Added Meeting Agenda&Notes for 27.05.2024 9:00 (Markus Raab, Daniel)
- Added Meeting Agenda&Notes for 03.06.2024 9:00 (Markus Raab, Jannis)
- Added Meeting Agenda&Notes for 10.06.2024 9:00 (Markus Raab, Moritz)
- Added Meeting Agenda&Notes for 17.06.2024 9:00 (Markus Raab, Christoph)
- Added Meeting Agenda&Notes for 24.06.2024 9:00 (Markus Raab, Moritz)
- Added Meeting Agenda&Notes for 27.06.2024 14:00 (Markus Raab, Christoph)
- Added Meeting Agenda&Notes for 15.07.2024 09:00 (Markus Raab, Lukas)
- Added Meeting Agenda&Notes for 22.07.2024 09:00 (Markus Raab, Christoph)
- Added Meeting Agenda&Notes for 02.08.2024 09:00 (Markus Raab, Stefanie)
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 tolife_cycle
. #close 724 (Jannis Adamek) - Users can now create, update, rename, reorder and deleted layers. #close 1336 (Jannis Adamek, Daniel Steinkogler)
- Add
notes
todrawings
to matchplantings
(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)
- changed release name from 0.3.7 to 0.4.0 (Filip Markovic)
- 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
. Removescale
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)
- 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)
- Enable automatic image scaling in base layer (Moritz)
- Add concept for key handling (Daniel Steinkogler)
- Refactor keybindings according to new keybinding concept (Daniel Steinkogler)
- 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)
- 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)
- 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)
- 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)
- 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) - 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)
- 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 layersMap
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:
Zustand (Global State Management):
React Query (Server State Management):
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 sourceexternal_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
andis_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
Other minor problems:
- fix Labiatae to be lamiaceae (family rank)
- Remove all "var." from the database entries (staying with the 3 words).
from Reinsaat
Unique name:
- use
Scientific name subheading
together withname
(as cultivar, see above) for ourunique_name
(Cucurbita ssp.
fromScientific name kulturhinweise
shouldn't exist) - Remove all occurrences of
L.
,MIll.
, andvar.
. - 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 beHelianthus annuus
Further Readings
- Rationale is explained in this decision.
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.
Related Decisions
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
Related Decisions
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
Related Decisions
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.
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 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).
Related Decisions
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.
See also SeaORM documentation.
Decision
We use diesel_async
with postgis-diesel.
See also Diesel Documentation.
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
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
Related Decisions
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 howmain.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
Related Decisions
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
Related Decisions
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
Related Decisions
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.
Related Decisions
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.
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.
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.
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.
Related Decisions
NA
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
Related Decisions
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
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
Related Decisions
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
Related Decisions
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 withlegacy-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 fromTypeDoc
automatically.
Related Decisions
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
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
Related Decisions
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.
Related Decisions
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.
Related Decisions
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.
Related Decisions
- 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
Related Decisions
- Choosing React as the frontend library for PermaplanT
Notes
Links
- https://medium.com/readytowork-org/its-zustand-vs-redux-8e24424df713
- https://tanstack.com/query/latest/docs/react/guides/does-this-replace-client-state
- https://tanstack.com/query/v4/docs/react/comparison
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
Related Decisions
- 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.
Related Decisions
Notes
The canvas library, that we use, provides a suggestion on how to implement undo-redo functionality with the canvas2:
- 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
Related Decisions
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 thatwater_requirement = dry
those belong together. - However:
amarena cherry alternate_name = Pacific silver fir
doesn't work as it isn't clear which parts ofPacific silver fir
belong toalternate_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.)
Related Decisions
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
Related Decisions
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
Related Decisions
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 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
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 parameterpage
andper_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 successfulPOST
requests - all ways client could behave wrongly1 using 4xx error codes
- specific 2xx codes, e.g., we use
1 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" = [])
)
)]
Further Readings
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
andClone
(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 beUPPERCASE
- 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
overVARCHAR(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
overSEQUENCE
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.
Links
Generously use links but be very careful to create a coherent documentation (German: "roter Faden"):
- Clearly separate between prerequisites and further readings.
- Prerequisites: Concepts people need to know before reading the documentation must be linked in the beginning.
- When adding links, check if users cannot easily get lost in circles.
- To link to PermaplanT's files use internal links. Use absolute or relative links as appropriate. E.g. for files within the same folder use relative links.
- For external links use https links, if available.
Takeaway: Links are very helpful to readers. Make sure documentation can be read one after the other with these links (German: "roter Faden").
Templates
In general we use arc42.org but we use specialized templates for:
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 methodclick_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"),
},
});
Further reading
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
})
}
Further reading
- https://tkdodo.eu/blog/effective-react-query-keys
- https://tkdodo.eu/blog/leveraging-the-query-function-context
Deep Dive (whole blog series)
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
orhooks
folder. - Create a main TypeScript file for the layer (e.g.,
NewLayer.tsx
). - Inside
components
create aNewLayerLeftToolbar.tsx
and aNewLayerRightToolbar.tsx
. - Inside the
newLayer
folder create a file actions.ts.
- If your layer requires API interactions, create an
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 theTrackedMapStore.ts
.
- Define a hook for your layer (e.g.,
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 toMapStoreTypes.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 actionexecute
: commits the changes over the apireverse
: undoes the actionapply
: 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:
- add keybinding to json configuration for the corresponding action
- bind a keyhandler to the component that should handle the key event if focused
- retrieve the action name configured for the pressed shortcut using helper methods from
config/keybindings/keybindings.ts
- 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:
- add keybinding to json configuration for the corresponding action
- create action handlers that maps the action name to the corresponding function that should be triggered
- use
createKeyHandlersFromConfig
helper method fromconfig/keybindings/keybindings.ts
to create map of shortcuts to action handlers according to config - 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
Further Readings
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 filetailwind.config.js
.)
- 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
-
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
ortracking-tight
- Running text:
tracking-wide
ortracking-wider
)
- Headings: use negative values for the bigger headings h1-h3, i.e.
- Always go with the default value, i.e.
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
- border color:
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 ofpadding
. - Make call-to-action buttons look the same everywhere by using our
SimpleButton
component. Use Tailwind's classes to define the button'smargin
andwidth
, 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 thenot-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 clickingX
in the status barESC
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
inapi
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
andLayerListItem
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 respectivei18next
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 theseeds
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 ofbtn
).
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
- 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
- guidelines
- 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:
-
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:
- stability
- maintenance
- performance
- 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)
- quality goals:
- documentation:
- mdBook (general intro)
- API documentation (swagger?)
- code documentation of backend
- 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
- API documentation
- 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
- ...
- Examples are
- 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 relationshipA companion B
is identical toB 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
- Left side
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:
- commit hooks
- PostGIS full text search
- react query for new features
- Which ORM crate/setup do we want?
- How to store plant relationships?
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
- guidelines
- 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
- it is hard to remember to keep the file structure in the language the same as the features:
- 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:
- commit hooks
- PostGIS full text search
- react query for new features
- Which ORM crate/setup do we want?
- How to store plant relationships?
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
anddto
exists as file and directory in themodel
package. Shouldn't they both be a regular package of their own? - Both
entity
anddto
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 ofcontroller
. - 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?
- Both
- Can I clean up the backend structure? Some things seem messy.
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
- Done:
- 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
-
- 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:
- shortly say what you think that the author wanted to say
- which sentence was the most difficult one to read
- 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; }
- axios configuration wrapper in 'frontend/src/axios'
import and call createAPI() for requests to the backend and createNextcloudAPI() for requests to Nextcloud
example:
- frontend auth: https://github.com/ElektraInitiative/PermaplanT/pull/351
- 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:
- shortly say what you think that the author wanted to say
- which sentence was the most difficult one to read
- 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:
- search (text) -> list of plants
- plant_info () -> info, list plant_ID of relations, array of 1m raster, maybe picture/heat map
- 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:
- shortly say what you think that the author wanted to say
- which sentence was the most difficult one to read
- 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
orchromium --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 (in
manual/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
cansee, 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.
-
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:
- urgent/release critical tasks
- get PRs merged
- finish UC
- 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)
-
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:
- yellow triangle as warning if changes might have unwanted effects
- 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:
- TISS
- short mid-term presentation (Moritz already done)
- 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 tolife_cycle
, to be used when notime_to_harvest
is available). Theremoved_on
date will be set by adding a plantstime_to_harvest
to itsadded_on
date after planting a plant. - When planting a new plant, the whole interval from
added_on
toremoved_on
should be considered, not justadded_on
- If no
removed_on
date can be determined then only theadded_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
-
- / 11.8.
-
- / 18..8.
-
- / 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.
Meeting 05.08.2024
Attendees
- Markus
- Christoph (Protocol done)
- Stefanie (Protocol done)
- Andrei
- Filip
- Yvonne
- Jannis
needed to go earlier:
- Lukas (Protocol done)
Buddies
- Stefanie & Christoph & Andrei
- Jannis & Lukas
Agenda
- 09:00 start
- welcome round: Permaculture Principles
- protocol: Andrei
- 0.4.2. release
- successfully done
- thanks for everyone involved
- nodejs version upgrades (20.16)
- fix dev
- review round technical texts:
- review list
- reverse engineering of text
- Front Page Updates
- connect "Apply" button with KeyCloak?
- live meeting 25.08.
- Task Board
Tasks for Everyone
Review MRs on submissions until Monday 05.08.2024
To be done until Friday 09.08.2024:
- buddy talk: discuss and apply Permaculture Principles
- 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 09.08.2024:
- Filip: fix dev branch, test maps, collect data (2000 concurrent users, why is image loading so slow?)
- Lukas: Shading fixes, mockup for shading&moisture&soil
- Jannis: complete MRs, hydrology&soil type backend implementation, fixes
- Stefanie: e2e UI testing dev+groups, estimations
- Christoph: continue hierarchy
- Andrei: categorize and improve issues, remembering viewing state
Meeting Notes
Release 0.4.2:
- Everything is good, thanks to everyone involved
- Many features in dev are not yet ready for release, fixing them is our next goal
- We also need to fix infrastructure (upgrading to Devuan stable)
Updating Frontend packages:
- MR is ready to be reviewed by people, upgrading to Node version 20 does not have side effects. It should be merged into dev, master stays with old versions for now. Reviewers should test if things are working normally.
Dev fixes from Filip:
- still needs to be looked into a bit, should be resolved this week
- report if there are other issues with the pipeline and support Filip in fixing it if possible
Regressions in dev:
- Christoph and Stefanie tested and opened some new issues, some more to come (from test report)
Technical texts:
- Review all texts and approve the MRs (by end-of-day)
Proposal for new landing page:
- little tweaks to improve the design of the landing page
- Andrei: looks good
- Christoph: dark blue on dark background might be a bit too dark overall ('fruitful' in the banner)
- Filip: really like the picture in the "hero"-banner
- Jannis: image looks good, maybe a different color for 'fruitful'
- Lukas: Membership cards look modern
Lukas tasks:
- too many issues, maybe some should be moved to next iteration
- hydrology can be moved as backend is not ready
- maybe make mock-up on how the layers should look
- Legend - remove from the current location as users would not read it there, instead integrate the colors into the buttons, maybe text as tooltip, or when the button is selected the legend shows up under the buttons.
- Crop rotation: some leftover issues regarding the heatmap backend code (traffic lights)
- start with "fix shadings calculations"
Filip tasks:
- Fixing dev
- Test Maps
- Start collecting the data
Requesting membership on front page:
- Current button with "mailto" is not a very good solution, we should replace it with something else
- It needs to be investigated if a solution which directly creates users in keycloak is possible
- An alternative would be database entries or an email service from the backend
Live meeting:
- most likely date: 25th of August
- Christoph will ask Daniel :-)
Jannis tasks:
- hydrology and soil layer task
- Docker setup improved documentation -> wait for the frontend packages update
- migrations -- to be reviewed by Christoph
Stefanie tasks:
- test cases -- they tested locally for now
- another test run after frontend packages MR and group instead of layers MR are merged to dev
- e2e testing - meet with Christoph and look into adding test cases for performance
- write new issues about problems with seeds
- please provide estimates for issues
Christoph tasks:
- write rules about traffic light system
- write the questions in the follow-up issue so they don't get lost in the MR
- continue with hierarchy
Andrei tasks:
- first merge "master into dev" before the FE package update
- continue work on remember view state
- check what else can be done, provide estimates
Meeting 12.08.2024
Attendees
- Markus
- Stefanie (Protocol done)
- Jannis
- Yvonne
not here:
- Andrei (Protocol done)
cannot come:
- Christoph (Protocol done)
- Lukas (Protocol done)
- Filip
Buddies
- Stefanie & Christoph & Andrei
- Jannis & Lukas
Agenda
- 09:00 start
- Archilles tendon
- protocol: Jannis
- holiday 28.8. -> 5.9., no regular meeting 2.9.
- fix dev
- diversity improvement in search
- review round technical texts:
- short, clear sentences
- strong verb as early as possible
- small submissions without clutter (template etc.)
- usage of code, formulas, diagrams, ...
- upgrades
- NodeJS 20
- PostgreSQL 15
- live meeting 25.08.
- Task Board
Tasks for Everyone
To be done until Friday 16.08.2024:
- submit a page of text in submissions
- buddy talk: discuss and apply Permaculture Principles
- update to nodejs 20.16 on your machine
- upgrade to PostgreSQL 15
- 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 16.08.2024:
- Stefanie: RQs, look into tools, bug fixing
- Jannis: complete MRs, hydrology&soil type backend implementation, fixes, write methods, klarheit über issues
Was not here:
- Filip: fix dev branch, test maps, collect data (2000 concurrent users, why is image loading so slow?)
- Lukas: Shading fixes, mockup for shading&moisture&soil
- Christoph: continue hierarchy
- Andrei: categorize and improve issues, remembering viewing state
Meeting Notes
Discussed: It would be benefitial to seperate NewPlantingDto (post) from PlantingDto (get) but as this is not urgend => work around it for now and not do any seperation.
live meeting on 2024-08-25.
Meeting 19.08.2024
Attendees
- Markus
- Stefanie
- Andrei
- Christoph
- Filip
Only listen:
- Lukas
Cannot come:
- Yvonne
- Jannis
Buddies
- Stefanie & Christoph & Andrei
- Jannis & Lukas
Agenda
- 09:00 welcome
- protocol: Christoph
- holiday 28.8. -> 5.9., no regular meeting 2.9.
- all CI pipelines green again
- all MRs now on dev, except:
- landing page updates
- CI fixes not specific to dev (keep Jenkinsfile consistent)
- PermaplanT Fest
- 25.08.
- Anreisemöglichkeiten Wien Hbf -> Deutschkreutz um 08:23 -> 09:47 oder 09:23 -> 10:47
- Car Sharing?
- Any questions?
- colors
- heatmap:
- check on every date too resource intensive?
- entity.rs:
- Christoph: family?
- Task Board
Left for next time:
- branch names:
- keep default of GitLab?
- don't use special characters like
#!
- brushing layer architecture (enum?)
- crop rotation
- Lukas: drought tolerance
Tasks for Everyone
To be done until Friday 23.08.2024:
- buddy writing (Schreibtreffen)
- submit a page of text in submissions
- 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 23.08.2024:
- Filip: test maps, collect data (2000 concurrent users, why is image loading so slow?)
- Christoph: RQs, continue hierarchy
- Andrei: RQs, categorize and improve issues, remembering viewing state
- Stefanie: RQs, look into tools, bug fixing
Only listen:
- Lukas: Shading fixes, mockup for shading&moisture&soil
Not here:
- Jannis: complete MRs, hydrology&soil type backend implementation, fixes, write methods, klarheit über issues
Meeting Notes
No meeting on 02.09.2024
Filip included a test map on https://mr.permaplant.net, further maps to come.
From now on everything will target dev except landing page updates and CI fixes.
Heatmap colors to be decided after color settings table issue is done. #1525
We shouldn't use special characters like '#' in branch names.
We'll leave the family field in the plants entity in entity.rs to be used later with the hierarchy rework.
If it's clear how to incorporate feedback you can merge directly but if it is a bigger change / refactor you can make a new submission of the corrections. The submission should be focused on one chapter (e.g. introduction, methods, ...).
Take small steps, e.g. for finding a research question:
- Brainstorming
- Deciding on the RQ
- Refining the RQ
- Deciding on tools
This is not necessarily in these steps and sometimes also iterations are needed.
Mockups
Related
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 withgrep -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.
Further Related Resources
- 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 (Cross-Origin Resource Sharing)
"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
.
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 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.
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.
Additional name on map: left toolbar
- 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
TC-001 - Login
- Description: Successfully login to PermaplanT
- Preconditions:
- Test Steps:
- Press the login button on the navbar.
- Enter credentials.
- 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:
- 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:
- Go to the map editor page.
- Create a new map.
- 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:
- Go to the map editor page.
- Create a map with a name that already exists.
- 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:
- Naviagate to the map page.
- Select a map.
- Select the plant layer in the right map menu.
- 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:
- Naviagate to the map page.
- Select a map.
- Select the plant layer in the right map menu.
- Push the search icon in the lower right menu.
- 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:
- Navigate to the map page.
- Select a map.
- Select the plant layer in the right map menu.
- Push the search icon in the lower right menu.
- 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:
- Add a planting to the map.
- Click on the date selection on the bottom of the screen.
- Navigate to a date in the past.
- 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:
- Add a planting to the map.
- Click on the date selection on the bottom of the screen.
- Navigate to a date in the past.
- Wait 1 second.
- 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:
- Add a planting to the map.
- Click on the planting.
- Click on the
Add Date
date selector in the left lower toolbar. - 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:
- Add a planting to the map.
- Click on the planting.
- Click on the
Remove Date
date selector in the left lower toolbar. - 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:
- Add a planting to the map.
- Click on the planting.
- Click on the
Add Date
date selector in the left lower toolbar. - Change the date to a date in the future.
- Wait one second
- 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:
- Select a base layer image.
- Set the base layer rotation to 45 degrees.
- Scale the base layer image to 50 px per meter.
- 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:
- Press the grid button in the left upper menu bar.
- Zoom all the way in.
- 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:
-
⚠️ 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.
TC-001 - Login
- Description: Successfully login to PermaplanT
- Preconditions:
- Test Steps:
- Press the login button on the navbar.
- Enter credentials.
- 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:
- 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:
- Go to the map editor page.
- Create a new map.
- 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:
- Go to the map editor page.
- Create a map with a name that already exists.
- 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:
- Navigate to the map page.
- Select a map.
- Select the plant layer in the right map menu.
- 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:
- Navigate to the map page.
- Select a map.
- Select the plant layer in the right map menu.
- Push the search icon in the lower right menu.
- 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:
- Navigate to the map page.
- Select a map.
- Select the plant layer in the right map menu.
- Push the search icon in the lower right menu.
- 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:
- Add a planting to the map.
- Click on the date selection on the bottom of the screen.
- Navigate to a date in the past.
- 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:
- Add a planting to the map.
- Click on the date selection on the bottom of the screen.
- Navigate to a date in the past.
- Wait 1 second.
- 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:
- Add a planting to the map.
- Click on the planting.
- Click on the
Add Date
date selector in the left lower toolbar. - 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:
- Add a planting to the map.
- Click on the planting.
- Click on the
Remove Date
date selector in the left lower toolbar. - 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:
- Add a planting to the map.
- Click on the planting.
- Click on the
Add Date
date selector in the left lower toolbar. - Change the date to a date in the future.
- Wait one second
- 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:
- Select a base layer image.
- Set the base layer rotation to 45 degrees.
- Scale the base layer image to 50 px per meter.
- 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:
- Press the grid button in the left upper menu bar.
- Zoom all the way in.
- 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:
- Follow the Guided Tour until its end.
- 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:
- Leave the page by entering a different URL or using the browsers navigate back button.
- Return to the map editor screen.
- Use the cancel button on the Tour step or press ESC.
- 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:
- Press Button "Edit seed"
- Change an attribute of the seed.
- Submit the form.
- 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:
- 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
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?
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:
- Press Button "Edit seed"
- Change an attribute of the seed.
- Submit the form.
- 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:
- 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
Error Analysis
No errors occured during the tests.
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?
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:
- Press Button "Edit seed"
- Change an attribute of the seed.
- Submit the form.
- 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:
- 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
Error Analysis
"Sorry I couldnt load your image" error occured on opening a fresh map.
Closing remarks
How is the current state of the software?
The software is in a good state. The image loading error is a known bug, it still exists.
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?
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.
Additional name on map: left toolbar
- 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.
Additional name on map: left toolbar
- 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: Filip, Stefanie
- Date/Time: 01.08.2024
- Duration: 30 Minutes
- Commit/Tag: 03e97dadad765070e8efcbdb4c9f1dc55479c298
- Setup: master.permaplant.net
- Planned tests: 27
- Executed tests: 26
- ✔️Passed tests: 26
- ⚠️Problematic tests: 0
- ❌Failed tests: 0
Error Analysis
Closing remarks
- How is the current state of the software? Overall in a good state, minor errors and UI issues.
- Have the quality objectives been achieved? Usability can be improved.
- What are the consequences drawn from the current state, including: how can future errors be avoided, how can the development process be improved? Usability Tests, Mockups
Errors found
1. When logging out while in a map, 4 error toast messages get shown on screen.
2. Error has been previously specified.
3. Class 6: Cosmetic issue
4. Level 3: Correction will be done opportunistically
1. When using the measurement tool, it is not clear that the right button stops the measuring.
2. No
3. Class 6: Cosmetic issue
4. Level 3: Correction will be done opportunistically
1. When using the measurement tool, closing the bottom status bar draws a measuring to the X of the status bar.
2. No
3. Class 6: Cosmetic issue
4. Level 3: Correction will be done opportunistically
1. When changing opacity of a layer, the cursor could better indicate that the line is changeable
2. Not yet identified
3. Class 6: Cosmetic issue
4. Level 3: Correction will be done opportunistically
Test cases
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 wanted 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:
- 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: Description of plant relations says what a red line indicates, but no red line is shown on the map.
- 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.
Additional name on map: left toolbar
- 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:
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:
Heatmap (only in dev branch)
- 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:
Map Overview: More than 30 Maps 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:
General
- Tester: Stefanie, Christoph
- Date/Time: 01.08.2024 19:26
- Duration: 1h
- Commit/Tag: a5658b7abfda3d4b990cb27d8119fd0ce7623d79
- Setup: local dev
- Planned tests: -52
- Executed tests: -38 (skipped duplicates and no longer relevant tests)
- ✔️Passed tests: -38
- ⚠️Problematic tests: -0
- ❌Failed tests: -0
Error Analysis
- 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? Overall in a good state, improvements can be made on some features
- Have the quality objectives been achieved? Mostly yes, for improvements see notes
- What are the consequences drawn from the current state, including: how can future errors be avoided, how can the development process be improved? Same as on master test report: Usability tests, Mockups
Manual Test Protocol
Notes (not errors)
Currently there are no plants in the database on dev.permaplant.net, so the test were done locally.
The scaling steps when zooming on the map are a bit harsh and could be improved by reducing the step size.
Loading indicator barely visible in dark mode
Scrollbar while changing shading type
Distance measurement:
- Improve help message
- Click on X in status panel or pressing escape adds another line
Improve manual tests:
- Extend test by shades "Layer Management: Correct konva rendering of layer order on new map"
- Move test "Map Editor Guided Tour" to top of list
- Specify what are "Problematic tests"
- 11 tests are duplicates (marked DUPLICATE)
- Three tests are no longer relevant (marked NO LONGER RELEVANT)
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.
Additional name on map: left toolbar
- 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: DUPLICATE
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: DUPLICATE
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: DUPLICATE
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: DUPLICATE
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: DUPLICATE
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: DUPLICATE
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: DUPLICATE
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: DUPLICATE
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:
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: DUPLICATE
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: DUPLICATE
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: DUPLICATE
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:
- Notes: NO LONGER RELEVANT
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:
- Notes: NO LONGER RELEVANT
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:
- Notes: NO LONGER RELEVANT
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:
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 onassigned
: use case is part of PermaplanT 1.0 (June 2024)done
: use case was successfully implementedlater
: currently not being worked on due to prioritiesdraft
: 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: 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.
- The user copies the selection on map A.
- 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:
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.
- User A copies the selection on his map.
- 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:
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.
- The user copies the selection by clicking on the copy icon in the toolbar.
- 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:
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.
- The user copies the selection by pressing CTRL-C.
- 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.
- The user pastes a copied selection without having clicked anywhere else on the map after copying.
- 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
orRelation 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.
- The user has opened the app and sees either
- 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 orange 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:
- 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: 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: 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 to not consider it for heatmap.
- 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: 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: 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: 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.
- Relations are individual elements or connect two elements, that are removed or added when adding, moving, removing, deleting or modifying elements on the map:
- 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:
Development
- relations are generated and stored in backend
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:
- First the user globally tells a pH topsoil value, soil weight and yield grade.
- 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.
- 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: 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.
- The user brushes permanent infrastructure:
- 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.
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
Current Use Cases
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 and Christoph
Scenarios
- Precondition: The user has opened the plant layer.
- Main success scenario:
- The user places a new plant.
- 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: None.
- Postcondition: None.
- Note: See relation layer for which relations exist.
- Environmental Constraints:
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
- The user selects layer A.
- 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.
- The user does visibility changes on a map.
- 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
- The map is shown with the same visibility settings it had when the user left it the last time, which includes:
- 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
andSets
.
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: 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
Done 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:
- 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)
- labels
- images
- The user successfully adds, edits, moves, removes and deletes custom elements in three tabs:
- 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
Left-Overs
- names not yet validated?
- arrows not implemented, see dimensioning
Use Case: Area of Plantings
Summary
- Scope: Plants Layer
- Level: User Goal
- Actors: App User
- Brief: The user can add, edit, move and delete area of plantings 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 plantings 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 an area of plantings 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 area of plantings as desired.
- If constraints are violated for the place where an area of plantings 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 plantings 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.
- User successfully imports an orthophoto or site plan to be used as a background by selecting the option to
-
Alternative scenarios:
- 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.
- User accidentally replaces the ortophoto with another image or wrongly put a line in the polygon and presses undo to correct the mistake.
- 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.)
- User selects an (additional) alternative image.
-
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
Use Case: Login
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.
Links
Left-Overs
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.
- The user successfully creates or duplicates a new map by providing:
- 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
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.
- 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:
- 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.
- The user sees events represented on the scrollbar of the timeline feature, allowing them to understand how the map changed over time.
Events include:
- 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: Stefanie
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:
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.
- The user sets the Added on date.
- 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: 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: 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 forpopcorn
.
- 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
- The user types something into the search text box.
- Alternative scenario:
- No match can be found for what the user was searching for.
A message will be displayed that nothing was found.
- No match can be found for what the user was searching for.
- 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.
- The two sides of the relationship can be
- Details about the relationship are provided by the user.
- 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.
- The user creates a relationship which is only effective for one or more of her selected maps.
- 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.
- The user tries to add a global relationship where another global with identical sides already exits.
- 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.
- The user can receive permacoins through various activities in the app, like:
- 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.
- Assignee: Stefanie
Scenarios
- Precondition: The user has opened the app and has selected any additional layer.
- Main success scenario:
- The user selects elements.
- A line with arrows at the end and the distance in the middle gets added.
- 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.
- The user can see a list of incomplete milestones and their respective requirements. An user can reach a certain milestone by e.g.:
- 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)
- show images
- text should be mark/copyable
- emoji
- reactions
- files
- reply
- directly share photo (take photo with phone)
- 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:
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.
- The set of map-specific favorites has changed according to the changes the user made.
- 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:
- The user can click an register button which leads them to Keycloak to fill out:
- username
- first+last name
- email address
- birthday
- biography
- The user can look at public maps (read-only and without seeing addresses!)
- The user apply for membership, with several steps:
- 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.
- 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)
- 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)
- form page 3
- owner (KontoinhaberIn)
- IBAN
- BIC
- how did you get to know about PermaplanT (optional text)
- username for who recruited (angeworben) (optional)
- privacy
- An admin:
- removes the bank account data
- assigns the "member" role in Keycloak
- changes quota in Nextcloud
- The user gets a notification via email
- The user can click an register button which leads them to Keycloak to fill out:
- 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:
- before going offline (browser is online)
- offline
- prepared for going online again (browser is online)
- 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: 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: 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: 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: 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: 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
- work well with already placed plants and
- fit the environmental conditions
- 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: 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: