docs: cleanup

docs/Contributing/0000-README.md

@@ -1,17 +1,56 @@
 # Contributing guidelines
 
-Common guidelines for contributing to FireFighter
-
 ## Foreword
 
 First off, thank you for taking the time to contribute!
-It's worth mentioning that the purpose of this document is to provide you with a
-set of general guidelines and not strict rules: nothing is set in stone, and we
-welcome contributions about these contributing guidelines as well :-)
 
-## Setup
+It's worth mentioning that the purpose of this document is to provide you with a set of general guidelines and not
+strict rules: nothing is set in stone and we welcome contributions about these contributing guidelines as well :-)
+
+## TL;DR
+
+We want to make contributing straightforward and easy for everyone. As such and unless otherwise stated, we will use the
+traditional GitHub fork and pull request workflow: any commit must be made to a feature/topic branch in a local fork and
+submitted via a pull request before it can be merged. If you are familiar with GitHub (and Git), branching and opening a
+pull request or an issue... then you should be able to start contributing right away.
+
+It is **strongly advised** to contact the project owner(s) **before** working on implementing a new feature or making
+any kind of large code refactoring.
+
+Contributors must agree to the following:
+
+- material without explicit copyright assignment will be assigned to [ManoMano](https://manomano.fr)
+- apart from a few identified exceptions, material must be licensed under the project's MIT license (see [LICENSE](../license.md))
+
+Contributors must also agree to follow the [code of conduct](../CODE_OF_CONDUCT.md).
+
+## Coding style
+
+> Refer to the [development guidelines](development.md) for more information.
+
+## Documentation
+
+We consider documentation as important as code. Substantial contribution must always come with exhaustive documentation.
+
+> Refer to the [documentation guidelines](documentation.md) for more information.
+
+## Tests
+
+Application and contributions should be tested and push for the highest quality standard.
+
+> Refer to the [development guidelines](development.md#testing) for more information.
+
+## Git
+
+See [development guidelines](development.md#git) for more information about the Git workflow.
+
+## Issues
+
+If you find a bug that you don't know how to fix, please create an [issue](https://guides.github.com/features/issues/):
 
-The project is a Django multi applications project.
-Lot of operation are managed using `pdm` or `docker-compose`
+- use a clear and descriptive title
+- give a step by step explanation on how to reproduce the problem
+- include as many details as possible, even ones that may seem irrelevant; [gists](https://help.github.com/articles/about-gists/) are a good way to include large amount of context and information
+- describe what was already tried to fix the problem
 
-You will need a working local Python environment with PDM, and Docker with docker-compose for the dependencies.
+> These contribution guidelines are adapted from the [ManoMano CONTRIBUTING guide](https://github.com/ManoManoTech/ALaMano/blob/master/CONTRIBUTING.md) repository.

docs/Contributing/development.md

@@ -1,16 +1,30 @@
 # Development
 
-We want to make contributing straightforward and easy for everyone. As such and unless otherwise stated we will use the traditional GitLab fork and pull workflow: any commit must be made to a feature/topic branch in a local fork and submitted via a merge request before it can be merged.
-It is **strongly advised** to contact the project owner(s) (Pulse team) **before** working on implementing a new feature or making any kind of large code refactoring.
+We want to make contributing straightforward and easy for everyone. As such and unless otherwise stated we will use the traditional Github fork and pull workflow: any commit must be made to a feature/topic branch in a local fork and submitted via a merge request before it can be merged.
+It is **strongly advised** to open a discussion or an issue **before** working on implementing a new feature or making any kind of large code refactoring.
 
-## Global principe
 
-- All merge request must be attached to Jira ticket, in the [FireFighter board](https://manomano.atlassian.net/secure/RapidBoard.jspa?rapidView=443)
-- Issues and merge requests should be in English.
+*Issues and merge requests should be in English.*
 
-## Step to start contributing
+## Git
+
+Make sure you have a [GitHub account](https://github.com/join).
+The *main* branch should be considered as the production/deploy branch.
+
+#### Forking workflow
+
+> Extensive information can be found in this excellent [forking workflow
+> tutorial](https://www.atlassian.com/git/tutorials/comparing-workflows#forking-workflow).
+
+In a nutshell:
+
+1. [Fork](https://help.github.com/articles/fork-a-repo) the repository and clone it locally.
+
+    ```bash
+    git clone https://github.com/${USERNAME}/firefighter-incident
+    cd firefighter-incident
+    ```
 
-1. Create a public fork of the FireFighter project
 2. Create a topic branch where changes will be done.
 
     ```bash
@@ -53,6 +67,33 @@ It is **strongly advised** to contact the project owner(s) (Pulse team) **before
     git push origin --delete ${MY_TOPIC_BRANCH}
     ```
 
+
+### Syncing a fork with its upstream
+
+This is used to keep a local fork up-to-date with the original upstream repository.
+
+1. Connect the local to the original upstream repository.
+
+    ```
+    git remote add upstream https://github.com/${USERNAME}/${REPONAME}
+    ```
+
+2. Checkout, fetch and merge the upstream master branch to the local one.
+
+    ```
+    git checkout main
+    git fetch upstream
+    git merge upstream/master
+    ```
+
+3. Push changes to update to remote forked repository.
+
+    ```
+    git push
+    ```
+
+See [GitHub help](https://help.github.com/articles/syncing-a-fork) for more information.
+
 ## Dev tooling
 
 Check all available commands using `pdm run --list`.
@@ -115,6 +156,8 @@ pdm run docs-serve
 > This is the equivalent of running `mkdocs serve` in the project root.
 // TODO Pre-commit hook
 
+Read more in [the documentation contribution docs](documentation.md).
+
 ## Conventions
 
 ### Code style

docs/Contributing/documentation.md

@@ -1,10 +1,26 @@
 # Documentation
 
 Substantial contribution must always come with exhaustive documentation. We consider documentation as important as code.
-All the documentation for the project FireFighter are on in the repository file.
+All the documentation for the project FireFighter are in the repository.
 
 If you see mistake or lack of information on a part of the project documentation, you can add it. If it's a technical part, you can add it directly in the code, using inline documentation (see the [development guideline](development.md))
 
 ## Documentation Formatting
 
 Although formatting is not enforced on the documentation, feel free to use the [VS Code extension `markdownlint`](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) to keep the Markdown style consistent.
+
+## Running the documentation locally
+
+The documentation is built with [MkDocs](https://www.mkdocs.org/), a static site generator for project documentation.
+
+To serve the documentation locally, run:
+
+```shell
+pdm run docs-serve
+```
+
+To build the documentation locally, run:
+
+```shell
+pdm run docs-build
+```

docs/Deploy/XX-logs-traces.md

@@ -8,13 +8,13 @@ FireFighter uses the [logging](https://docs.python.org/3/library/logging.html) m
 
 #### Production JSON
 
-FireFighter logs to stdout using a [JSON formatter][firefighter.firefighter.settings.components.logging.custom_json_formatter.CustomJsonFormatter].
+FireFighter logs to stdout using a [JSON formatter][firefighter.logging.custom_json_formatter.CustomJsonFormatter].
 
 The JSON formats adheres to DataDog's [JSON log format](https://docs.datadoghq.com/logs/log_collection/python/?tab=standard#json-format).
 
 #### Development
 
-In development mode, FireFighter logs to the console using a [Pretty formatter][firefighter.firefighter.settings.components.logging.pretty_formatter.PrettyFormatter]
+In development mode, FireFighter logs to the console using a [Pretty formatter][firefighter.logging.pretty_formatter.PrettyFormatter]
 
 ### Further Configuration
 

docs/FAQ.md

@@ -0,0 +1,108 @@
+# Frequently Asked Questions
+
+## Is FireFighter performant?
+
+FireFighter has not be built with performance in mind, and may not scale well.
+
+The goal is still to have response times under 1s, to provide a decent user experience, for all user interfaces (Slack, Web UI).
+
+API and Back-Office are not as critical, and may be slower.
+
+Nevertheless, we have been able to handle incidents with hundreds of messages, and hundreds of users, without any issue.
+
+If you have any important performance issue, please open an issue, and we will try to help.
+
+## Is FireFighter secure?
+
+We hope so! We have tried to follow best practices, but we don't provide any warranty.
+
+> If you find a security issue, [please report it to our security team](https://github.com/ManoManoTech/firefighter-incident/security/policy#reporting-a-vulnerability).
+
+## Is FireFighter production-ready?
+
+FireFighter is currently used in production by ManoMano, and has been used to handle thousands of incidents.
+
+Nevertheless, it was only recently open-sourced, and we are still working on improving the documentation, test coverage, and making the application more generic.
+
+## Can I use FireFighter without Slack?
+
+No. Slack is currently the only supported chat platform.
+
+The Slack App is the main way to interact with the system, and is the only way to interact with the system during an incident. Slack is currently also used as the user directory.
+
+## Can I use FireFighter only through Slack?
+
+No. The Web UI is required to interact with the application, and is the only way to configure the application.
+
+All incident-related actions during an incident can be done through Slack.
+
+## Can I use FireFighter without PagerDuty?
+
+Yes.
+
+## Can I use FireFighter without Confluence?
+
+Yes.
+
+## Can I use FireFighter without Jira?
+
+Yes.
+
+## Can I use _other provider_?
+
+Not yet.
+
+The application integrates with Slack, Confluence, PagerDuty and Jira.
+Providing more integrations is not planned, but we plan to help integrate with other systems, by exposing Python APIs and hooks.
+
+> This means that the runbook or postmortem back-end can only be Confluence, the ticketing system can only be Jira, and the alerting system can only be PagerDuty, for now.
+> If you want to use other systems, you will have to integrate with them yourself.
+> Please open an issue if you need help with that.
+
+## Can I interact with FireFighter through the API?
+
+Yes.
+
+The API is almost exclusively read-only, and is useful for read-only integrations and reporting.
+The API is not exhaustive, and is missing models and fields.
+Most GET routes supports filtering, ordering, and rendering in JSON, CSV or TSV.
+
+There is an API route to create an incident, if you want to integrate with other systems.
+All routes support Cookie and API Key authentication.
+
+Please check the OpenAPI schema or Swagger UI for more information.
+
+## Can I give access to the Back-Office to non-admin users?
+
+The current back-office works great, but lacks many safety features, and must be handled with caution.
+It is necessary to access it to configure some features (e.g.: define a metric type or cost type).
+
+Thus, we recommend only giving access to the Back-Office to trusted users.
+
+## What authentication methods are supported?
+
+The Web UI supports OpenID Connect, and can be configured to use any OIDC provider.
+
+## Is the Web UI accessible? Responsive? Reliable?
+
+The Web-UI was built with progressive enhancement in mind, and should work without JavaScript, although the experience will be degraded.
+
+The Web-UI has not yet been tested with screen readers, and may not be accessible.
+
+The Web-UI is not regularly tested with mobile devices, and may not provide a good experience on small screens or screens with unusual aspect ratios.
+
+> If you have any accessibility issue, please open an issue, and we will try to help.
+
+## Do you support Slack Enterprise Grid?
+
+No. We only support one workspace, and do not support Enterprise Grid.
+
+> If you need support for Enterprise Grid, please open an issue, and we will try to help.
+
+## Do you support free Slack workspaces?
+
+Yes. We support free Slack workspaces, but we some features may not work (e.g. usergroups are not supported).
+
+## Do you support Slack OAuth?
+
+No. We don't support Slack OAuth.