Add Code of Conduct and Contribution Guide; Update Documentation (#219)

* add code of conduct based on official GitHub template

* add contribution guide

* fix: update old mermaid diagram

* docs: update and expand wiki pages for authentication, backend, architecture, environment variables, and various features

* docs: update German translation status to specify formal usage

Author: domai-tb

CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at dev@asta-bochum.de. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

CONTRIBUTION.md

@@ -0,0 +1,29 @@
+<h2 align="center">Thanks for deciding to contribute to Campus App 🎉💡</h2>
+
+### How to contribute?
+
+If you'd like to contribute, start by searching through the issues and pull requests to see whether someone else has raised a similar idea or question.
+
+If you don't see your idea listed, and you think it fits into the goals of this project, do one of the following:
+
+- If your contribution is minor, such as a typo fix, open a pull request.
+- If your contribution is major, such as a new guide, start by opening an issue first. That way, other people can weigh in on the discussion before you do any work.
+
+<img src="https://user-images.githubusercontent.com/56138477/213162795-f00d1f4c-3978-4017-a974-b65b40e70908.png" height="14" width="14" > [Discord server](https://discord.gg/zv8CCHRTjn)
+
+#### Steps to Contribute!
+
+Pull requests are the best way to propose changes to the codebase (we use Github Flow). We actively welcome your pull requests:
+
+- Fork the repo and create your branch from master.
+- Write clear meaningful git commit messages.
+- Make sure your code lints.
+- Issue that pull request!
+
+### Can you take an internship?
+
+**Yes!** As a computer science student, you can have an internship with the Campus App counted as a software project. Even if you are studying something else, you can contact us at any time at dev@asta-bochum.de.
+
+### Roadmap
+
+Current information on milestones and recent developments can be found in [this GitHub project](https://github.com/orgs/astarub/projects/16). Please keep in mind that we sometimes need a little more time to include bugs or features in the roadmap.

docs/wiki/Authentication.md

@@ -1 +1,18 @@
-> If we plan to implement the authentication, we will write this wiki page.
+# Authentication
+
+This page provides a short overview of authentication flows currently used in the app.
+
+---
+
+## Semesterticket Login
+
+The semesterticket flow uses the user provided RUB credentials (`loginId`, `password`).
+
+- Credentials are read from secure storage.
+- A headless webview performs the login flow.
+- Ticket information (Aztec code and metadata) is extracted and stored securely.
+
+Main implementation:
+
+- `lib/pages/wallet/ticket/ticket_datasource.dart`
+- `lib/pages/wallet/ticket/ticket_repository.dart`

docs/wiki/Backend.md

@@ -4,7 +4,7 @@ All commands are for Linux only. If you wish to use another OS, you will have to
 
 # Basic Concept 
 
-The backend of the Campus App serves as the main management unit for all processes the involve push notifications and data storage. 
+The backend of the Campus App serves as the main management unit for all processes that involve push notifications and data storage. 
 As of right now, [Appwrite](https://appwrite.io/) is used as our backend software. 
 
 Upon startup of the app a new user account or session, depending on whether an account already exists, is created.
@@ -25,7 +25,7 @@ The following features are currently backed by our backend:
 System requirements:
 - 1 CPU Core and 2GB of RAM
 - Docker 
-- Docker Dompose Version 2 
+- Docker Compose Version 2 
 
 Follow the installation guide as instructed here: https://appwrite.io/docs/installation
 

docs/wiki/Basic_Architecture.md

@@ -5,16 +5,15 @@ design patterns and principles.
 
 ## Folder Structure
 
-All the source code is located inside the `lib` folder and the corresponding unit
-tests inside the `test` folder. The first level inside these folders is always a
-main feature of the app like the Moodle, Flexnow or eCampus integration. Each
-of these features is structured via a [layerized architecture](https://medium.com/kayvan-kaseb/the-layered-architecture-pattern-in-software-architecture-324922d381ad).
+All source code is located inside the `lib` folder and unit tests inside the `test` folder.
+Feature modules are mainly organized below `lib/pages` and follow the project layering
+approach where applicable.
 
-The source code inside the `lib` folder is separated in three parts `core`, `pages`
-and `utils`. The `core` folder contain all features (like authentication) and basic
-functionalities which are used in multiple pages. The `pages` folder contain all
-independent features and inside `utils` you can find all helper functions and classes
-like APIs. The `test` folder is structured the same way.  
+The source code inside `lib` is mainly separated into `core`, `pages`, `utils`, `env`
+and `l10n`. The `core` folder contains shared app services and infrastructure
+(e.g. backend repository, settings and dependency injection). The `pages` folder
+contains feature modules. Inside `utils` you can find shared helper classes.
+Current tests are mainly located in `test/pages`.
 
 As a tree-structure our project looks at follows:
 
@@ -32,15 +31,22 @@ As a tree-structure our project looks at follows:
 │   ├── core
 │   │   ├── feature-xyz
 │   │   ├── themes
+│   │   ├── settings
+│   │   ├── ...
+│   ├── env
+│   │   ├── env.dart
+│   │   ├── env.g.dart
+│   ├── l10n
 │   │   ├── ...
 │   ├── pages
 │   │   ├── feature-xyz
 │   │   ├── ...
 │   ├── utils
-│   │   ├── apis
 │   │   ├── pages
+│   │   ├── widgets
 │   │   ├── ...
-|    ...
+│   ├── main.dart
+│   ├── firebase_options.dart
 ├── test
 │   ├── core
 │   │   ├── ...
@@ -83,22 +89,22 @@ about this architecture. For future reading you can read the [explaination by Mi
 Let's start with a visualization of this architecture:
 
 ```mermaid
-graph BT;
-subgraph <h3>Infrastructure Layer
- api{API} -->|Raw Data| rds(Remote Datasource)
- db{DB} -->|Raw Data| lds(Local Datasource)
+flowchart BT
+subgraph infra[Infrastructure Layer]
+	api{API} -->|Raw Data| rds[Remote Datasource]
+	db{DB} -->|Raw Data| lds[Local Datasource]
 end
-subgraph <h3>Domain Layer
- rds -->|Model| repo
- lds -->|Model| repo
- repo(Repository) -->|Entity| uc(Use Cases)
+subgraph domain[Domain Layer]
+	rds -->|Model| repo[Repository]
+	lds -->|Model| repo
+	repo -->|Entity| uc[Use Cases]
 end
-subgraph <h3>Application Layer
- uc --> appl(Presentation <br> Logic Holder)
- repo -.->|Entity| appl
+subgraph app[Application Layer]
+	uc --> appl[Presentation Logic Holder]
+	repo -.->|Entity| appl
 end
-subgraph <h3>Presentation Layer
- appl --> wid(Widgets)
+subgraph presentation[Presentation Layer]
+	appl --> wid[Widgets]
 end
 ```
 
@@ -120,9 +126,9 @@ interactions.
 The Application Layer handles the state of our App. All user requests coming from the
 UI are validated and handled at this point. So validation also into this layer. It could be argued that Validation goes into the domain, but the risk there is that errors raised may reference fields not present in the View Model which would cause confusion.
 
-In Flutter their a Stateful-Widgets which can handle the State by them self and
-global states can be handled by Change Notifiers. So their aren't different files
-for the Presentation and Application Layer. [¹]
+In Flutter there are StatefulWidgets which can handle state by themselves and
+global state can be handled by ChangeNotifiers. Therefore there are not always separate
+files for Presentation and Application Layer. [¹]
 
 ### Domain Layer
 

docs/wiki/Environment_Variables.md

@@ -1,10 +1,27 @@
 # Environment Variables
 
-In order to test the backend service you will have to set your own API key, for your very own server, in order to use the ``create_user`` function.
-
-To do that you will have to:
-- Create an .env file in the root directory
-- Set the value of ``APPWRITE_CREATE_USER_AUTH_KEY`` to your function's api key
-- Rebuild the ``env.g.dart`` file in the ``/env/`` folder, using the ``flutter pub run build_runner build`` command
-- Re-add all other previous keys e.g. the mensa api key and the firebase key, but make sure to replace the value of ``APPWRITE_CREATE_USER_AUTH_KEY`` with the newly generated output
-- Start debugging
+The app uses `envied` and reads secrets from a `.env` file in the project root.
+
+---
+
+## Required keys
+
+The following keys are currently used by `lib/env/env.dart`:
+
+- `MENSA_API_KEY`
+- `FIREBASE_ANDROID_API_KEY`
+- `FIREBASE_IOS_API_KEY`
+- `APPWRITE_CREATE_USER_AUTH_KEY`
+- `SENTRY_DSN`
+
+---
+
+## Setup
+
+1. Create a `.env` file in the project root.
+2. Add all required keys to the file.
+3. Generate `lib/env/env.g.dart` with:
+
+`flutter pub run build_runner build --delete-conflicting-outputs`
+
+4. Start the app.

docs/wiki/Getting_Started.md

@@ -1,4 +1,4 @@
-This pages will explain how to setup your development environment and first steps to start contributing to our project.
+This page explains how to set up your development environment and the first steps to start contributing to our project.
 
 ---
 
@@ -10,11 +10,10 @@ First you need to install Flutter. The [official flutter documentation](https://
 
 ## Setup an editor and emulator
 
-To write code you need an editor or IDE (obvously :D ). Wer would recommend to follow
-the official steps for VS Code by the [official flutter documentation](https://docs.flutter.dev/get-started/editor?tab=vscode).
+To write code you need an editor or IDE. We recommend to follow the official VS Code setup from the [Flutter documentation](https://docs.flutter.dev/get-started/editor?tab=vscode).
 
-In addition of the VS Code setup you need a running phone emulator. The best case, for non-MAC-users, is to install Android Studio Code and the included Virtual Device Manager.
-The [android developer documentation](https://developer.android.com/studio/run/managing-avds) provide a useful tutorial about AVD creation and management. We would recommend to create a phone with the newest Android API Level or at least API level 30 (Android 11.0). Google Play support is optional.  
+In addition to the editor setup you need a running phone emulator. For non-macOS users, Android Studio with the Virtual Device Manager is a good choice.
+The [Android developer documentation](https://developer.android.com/studio/run/managing-avds) provides a tutorial about AVD creation and management. We recommend using the newest Android API level (or at least API level 30). Google Play support is optional.
 
 ---
 
@@ -24,18 +23,20 @@ If you work the first time with git, check out this [cheat sheet](https://traini
 
 You can easily clone the repository with the command `git clone https://github.com/astarub/campus_app`. Git will create a new folder for you inside your current directory.
 
-Now you can open VS Code with the command `code ./campus_app` and start development.
+Now you can open VS Code with `code ./campus_app` and start development.
 
 ---
 
 ## Start development
 
-After opening VS Code you should open a terminal and update all flutter dependencies. For this, run the following command: `flutter pub get`.
+After opening VS Code, open a terminal and download dependencies with `flutter pub get`.
 
-Meanwhile you can start your emulator created privously. For that you can run: `flutter emulator --launch <emulator_name>`. 
+Meanwhile you can start your emulator with `flutter emulator --launch <emulator_name>`.
 
-In the end execute `flutter run` to start the app. Now, evertime you updated the source you can use the key `r` or `R` to update the running app.
-You can quite quit `q`.
+Then execute `flutter run` to start the app. After source changes you can press `r` or `R` for hot reload/restart.
+Press `q` to quit.
+
+If you work with custom backend credentials, also set up the `.env` file as described in `Environment_Variables.md`.
 
 Happy coding. :)