From 571cf62608e06c0dc8ecf00c976f8606c35370b4 Mon Sep 17 00:00:00 2001
From: Teal Bauer <teal@starsong.eu>
Date: Tue, 11 Mar 2025 11:22:12 +0100
Subject: [PATCH 1/2] Update README

Removed outdated information, added new features, normalized spelling,
---
 README.md | 113 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 81 insertions(+), 32 deletions(-)

diff --git a/README.md b/README.md
index fe4a03e..b9db3f6 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# C3Lingo rescheduled
+# c3lingo re:scheduled
 
 > Rapid assignment of shifts for chaos events
 
@@ -7,7 +7,7 @@
 ### Features
 
 - **Automatic schedule import** for re:publica, Pretalx/Hub
-- **Integrations** with [C3Lingo Filedrop](https://github.com/c3lingo/c3t-drop), [Engelsystem](https://github.com/engelsystem/engelsystem) and more
+- **Integrations** with [c3lingo Filedrop](https://github.com/c3lingo/c3t-drop), [Engelsystem](https://github.com/engelsystem/engelsystem) and more
 - **Collaborate live** on session changes using websockets
 - **One-click assignment** of angels
 - **Express interest** (with optional note) for sessions
@@ -19,6 +19,9 @@
 - **Manage source and target languages** per angel and per session
 - **Dark mode** and (mostly) responsive web app
 - **Statistics and leaderboards**
+- **Role-based access control** with flexible permissions
+- **Admin interface** for managing users, roles, and conferences
+- **Import history** with error tracking for conference data
 - ... and more 🎁
 
 ### Technologies:
@@ -26,13 +29,15 @@
 - [Ruby on Rails](https://rubyonrails.org/) with [SQLite](https://sqlite.org/) DB
 - [Tailwind CSS](https://tailwindcss.com/)
 - [Turbo](https://turbo.hotwired.dev/) + [Stimulus](https://stimulus.hotwired.dev/)
-- [ActionCables](https://guides.rubyonrails.org/action_cable_overview.html) with [Redis](https://redis.io/) backend
+- [ActionCable](https://guides.rubyonrails.org/action_cable_overview.html) with [Redis](https://redis.io/) backend
+- [Devise](https://github.com/heartcombo/devise) for authentication
+- [SolidQueue](https://github.com/rails/solid_queue) for background jobs
 
 ## Dev environment
 
 The project comes with a devcontainer for VSCode and compatible editors. Simply open the project folder in Code (or using `devcontainer open <path>`) and after a few seconds, a suitable container should be ready.
 
-Run `bin/dev` in the integrated terminal to start the dev webserver and the tailwind watch job (see `Procfile.dev` for details). Access your local rescheduled at http://127.0.0.1:3000.
+Run `bin/dev` in the integrated terminal to start the dev webserver and the tailwind watch job (see `Procfile.dev` for details). Access your local re:scheduled at http://127.0.0.1:3000.
 
 ## Secrets
 
@@ -46,25 +51,79 @@ The application requires some secrets, as of writing these include:
 
 You can supply the secrets by running `rails credentials:edit` or pass them as environment variable in upper case (e.g. `FILEDROP_USER`).
 
-## Preparation for an event
+## User and Role Management
 
-tbd.
+The application uses a role-based access control system with the following main roles:
+- `admin`: Full system access
+- `events_admin`: Can manage conferences and related resources
+- `shift_coordinator`: Can manage session assignments
 
-- talks about seeds
-- set "relevant stages"
-  ~~~ruby
-  relevant = ["Saal 1", "Saal ZIGZAG", "Saal GLITCH", "Stage HUFF", "Stage YELL", "Canceled talk"]
-  conf=Conference.find_by(slug: "38c3")
-  conf.relevant_stages=conf.stages.select { |val| relevant.include?(val[:name]) }
-  ~~~
-- sort stages
-  ~~~ruby
-  Stage.where(name: "Saal 1").update(weight: 10)
-  Stage.where(name: "Saal GLITCH").update(weight: 20)
-  Stage.where(name: "Saal ZIGZAG").update(weight: 30)
-  Stage.where(name: "Stage HUFF").update(weight: 40)
-  Stage.where(name: "Stage YELL").update(weight: 50)
-  ~~~
+### Managing Roles through the Admin UI
+
+Roles can be managed through the admin interface:
+1. Navigate to `/admin/roles` to view all available roles
+2. Click on a role to edit its permissions
+3. To assign roles to users, navigate to `/admin/users` and edit the user
+
+### Managing Roles with Rake Tasks
+
+You can also use the following rake tasks to manage user roles from the command line:
+
+```bash
+# View all users with special roles
+rake admin:list
+
+# List all events admin users
+rake admin:list_events_admins
+
+# Assign roles
+rake admin:make_admin[user@example.com]
+rake admin:make_events_admin[user@example.com]
+rake admin:make_shift_coordinator[user@example.com]
+
+# Remove roles
+rake admin:remove_admin[user@example.com]
+rake admin:remove_events_admin[user@example.com]
+rake admin:remove_shift_coordinator[user@example.com]
+```
+
+## Conference Management
+
+### Adding a New Conference
+
+Conferences can be added through the admin interface:
+1. Navigate to `/admin/conferences`
+2. Click on "Add New Conference"
+3. Fill in the basic information (name, slug, dates, time zone)
+4. Select the appropriate import job class (e.g., Pretalx, re:publica)
+5. Provide the required data fields for the selected import method
+6. Save the conference to initiate the data import
+
+### Importing and Updating Conference Data
+
+Conference data can be imported and updated through the admin interface:
+1. Navigate to the conference details page in admin
+2. Click on "Run Import Again" to start a new import
+3. The import process runs in the background with real-time progress tracking
+4. View the import history to see past imports and any errors
+
+### Setting Relevant Stages
+
+The admin interface provides a dedicated page for managing which stages are relevant:
+1. Navigate to the conference details page in admin
+2. Click on "Manage Relevant Stages"
+3. Check the boxes for stages that should be considered relevant
+4. Save your selection
+
+### Prioritizing Stages
+
+You can set the display order of stages through stage weights. Higher weights push stages down in the listing order:
+
+```ruby
+Stage.where(name: "Saal 1").update(weight: 10)
+Stage.where(name: "Saal GLITCH").update(weight: 20)
+Stage.where(name: "Saal ZIGZAG").update(weight: 30)
+```
 
 ## In production
 
@@ -100,16 +159,6 @@ By running `bin/rails <command>` you can trigger some helpful actions, such as
 
 ### In `rails console`
 
-- Manually trigger sync job
-  ~~~ruby
-  FetchConferenceDataJob.perform_now("38c3")
-  ~~~
-
-- Promote user to shiftcoordinator
-  ~~~ruby
-  User.find_by(name:"username_here").update(shiftcoordinator: true)
-  ~~~
-
 - Reset user password
   ~~~ruby
   pw = SecureRandom.alphanumeric(12)
@@ -133,4 +182,4 @@ By running `bin/rails <command>` you can trigger some helpful actions, such as
 
 ## License
 
-re:scheduled is licensed under the GNU Affero General Public License, Version 3.
+re:scheduled is licensed under the GNU Affero General Public License, Version 3.
\ No newline at end of file
-- 
GitLab


From 96667fed1a1e1a484b6e03677faed237519d80de Mon Sep 17 00:00:00 2001
From: Teal Bauer <teal@starsong.eu>
Date: Tue, 11 Mar 2025 11:27:42 +0100
Subject: [PATCH 2/2] Restructure README to be clearer

---
 README.md | 129 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 95 insertions(+), 34 deletions(-)

diff --git a/README.md b/README.md
index b9db3f6..99187f4 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,8 @@
 
 ## Overview
 
+re:scheduled is a web application for managing translation shifts at chaos events. It facilitates the coordination of translation angels, session scheduling, and real-time collaboration during events.
+
 ### Features
 
 - **Automatic schedule import** for re:publica, Pretalx/Hub
@@ -24,7 +26,7 @@
 - **Import history** with error tracking for conference data
 - ... and more 🎁
 
-### Technologies:
+### Technologies
 
 - [Ruby on Rails](https://rubyonrails.org/) with [SQLite](https://sqlite.org/) DB
 - [Tailwind CSS](https://tailwindcss.com/)
@@ -33,13 +35,15 @@
 - [Devise](https://github.com/heartcombo/devise) for authentication
 - [SolidQueue](https://github.com/rails/solid_queue) for background jobs
 
-## Dev environment
+## Getting Started
+
+### Development Environment
 
 The project comes with a devcontainer for VSCode and compatible editors. Simply open the project folder in Code (or using `devcontainer open <path>`) and after a few seconds, a suitable container should be ready.
 
 Run `bin/dev` in the integrated terminal to start the dev webserver and the tailwind watch job (see `Procfile.dev` for details). Access your local re:scheduled at http://127.0.0.1:3000.
 
-## Secrets
+### Secrets Configuration
 
 The application requires some secrets, as of writing these include:
 
@@ -51,21 +55,35 @@ The application requires some secrets, as of writing these include:
 
 You can supply the secrets by running `rails credentials:edit` or pass them as environment variable in upper case (e.g. `FILEDROP_USER`).
 
-## User and Role Management
+### Helpful Rails Tasks
+
+By running `bin/rails <command>` you can trigger some helpful actions, such as:
+
+- `rails c[onsole]`: Start interactive ruby shell
+- `rails db`: Start sqlite shell with the currently used DB
+- `rails db:prepare`: Create and migrate the database
+- `rails db:migrate`: Run pending DB migrations, automatically done by docker image on start
+- `rails db:seed` (Re-)import DB seeds from `db/seeds.rb`
+- `rails secret` generate a random secret, e.g. for `secret_key_base`
+- `rails generate` Powerful tool to generate boilerplate, run it to see list of options
+
+## Administration
+
+### User and Role Management
 
 The application uses a role-based access control system with the following main roles:
 - `admin`: Full system access
 - `events_admin`: Can manage conferences and related resources
 - `shift_coordinator`: Can manage session assignments
 
-### Managing Roles through the Admin UI
+#### Managing Roles through the Admin UI
 
 Roles can be managed through the admin interface:
 1. Navigate to `/admin/roles` to view all available roles
 2. Click on a role to edit its permissions
 3. To assign roles to users, navigate to `/admin/users` and edit the user
 
-### Managing Roles with Rake Tasks
+#### Managing Roles with Rake Tasks
 
 You can also use the following rake tasks to manage user roles from the command line:
 
@@ -87,9 +105,9 @@ rake admin:remove_events_admin[user@example.com]
 rake admin:remove_shift_coordinator[user@example.com]
 ```
 
-## Conference Management
+### Conference Management
 
-### Adding a New Conference
+#### Adding a New Conference
 
 Conferences can be added through the admin interface:
 1. Navigate to `/admin/conferences`
@@ -99,7 +117,7 @@ Conferences can be added through the admin interface:
 5. Provide the required data fields for the selected import method
 6. Save the conference to initiate the data import
 
-### Importing and Updating Conference Data
+#### Importing and Updating Conference Data
 
 Conference data can be imported and updated through the admin interface:
 1. Navigate to the conference details page in admin
@@ -107,7 +125,7 @@ Conference data can be imported and updated through the admin interface:
 3. The import process runs in the background with real-time progress tracking
 4. View the import history to see past imports and any errors
 
-### Setting Relevant Stages
+#### Setting Relevant Stages
 
 The admin interface provides a dedicated page for managing which stages are relevant:
 1. Navigate to the conference details page in admin
@@ -115,7 +133,7 @@ The admin interface provides a dedicated page for managing which stages are rele
 3. Check the boxes for stages that should be considered relevant
 4. Save your selection
 
-### Prioritizing Stages
+#### Prioritizing Stages
 
 You can set the display order of stages through stage weights. Higher weights push stages down in the listing order:
 
@@ -125,39 +143,63 @@ Stage.where(name: "Saal GLITCH").update(weight: 20)
 Stage.where(name: "Saal ZIGZAG").update(weight: 30)
 ```
 
-## In production
+## Daily Operations
 
-See [rescheduled-deploy](https://git.cccv.de/c3lingo/rescheduled-deploy) for a full docker-compose stack and more explanations.
+### Assignment Management
 
-# Colors (darkmode)
+Assignments can be created and managed through the web interface:
+1. Navigate to a session page
+2. Click on the "+" button next to an available slot to assign an angel
+3. The assignment is created in real-time and visible to all users
 
-- **text**: text-slate-300
-- **text (overlay)**: text-slate-200
-- **text light**: text-slate-400
+### Candidate Management
 
-- **logo**: text-white
-- **highlight**: text-red-500
+Angels can express interest in sessions:
+1. Navigate to a session page
+2. Click on "Express Interest" to mark yourself as a candidate
+3. Optionally add a note with additional information
+4. Shift coordinators can view and manage candidates from the session page
 
-- **dark background**: bg-zinc-700
-- **light background**: bg-gray-900
-- **overlay**: bg-gray-600
-- **input**: bg-zinc-900
-- **shadow**: gray-400
+### Notification System
 
-## Tips and Tricks
+The system can notify users about important events:
+- Assignment notifications
+- Schedule changes
+- Upcoming session reminders
 
-### Helpful `rails` tasks
+## Advanced Features
 
-By running `bin/rails <command>` you can trigger some helpful actions, such as
+### Integration with External Systems
 
-- `rails c[onsole]`: Start interactive ruby shell
-- `rails db`: Start sqlite shell with the currently used DB
-- `rails db:migrate`: Run pending DB migrations, automatically done by docker image on start
-- `rails db:seed` (Re-)import DB seeds from `db/seeds.rb`
-- `rails secret` generate a random secret, e.g. for `secret_key_base`
-- `rails generate` Powerful tool to generate boilerplate, run it to see list of options
+#### Filedrop Integration
+
+Documents related to sessions can be managed via the Filedrop integration:
+1. Navigate to a session's detail page
+2. Click on the "Filedrop" tab to see related documents
+3. Documents can be uploaded, viewed, and commented on
+
+#### Engelsystem Integration
+
+Sessions can be synchronized with the Engelsystem:
+1. Navigate to a session's detail page
+2. Click on "View in Engelsystem" to open the corresponding shift
+3. Changes in assignments can be synchronized between systems
+
+#### Telegram Notifications
+
+Important events can trigger Telegram notifications:
+- Use the notification settings to configure which events trigger notifications
+- Group chats can receive consolidated updates
+
+## Deployment
 
-### In `rails console`
+### Production Environment
+
+See [rescheduled-deploy](https://git.cccv.de/c3lingo/rescheduled-deploy) for a full docker-compose stack and more explanations.
+
+### Maintenance Tasks
+
+Some helpful maintenance tasks you can run in the Rails console:
 
 - Reset user password
   ~~~ruby
@@ -180,6 +222,25 @@ By running `bin/rails <command>` you can trigger some helpful actions, such as
   Candidate.includes(:user, :session).where.not(note: [nil, ""]).pluck('sessions.title','users.name', :note)
   ~~~
 
+## Appendix
+
+### UI Styling Reference
+
+#### Colors (darkmode)
+
+- **text**: text-slate-300
+- **text (overlay)**: text-slate-200
+- **text light**: text-slate-400
+
+- **logo**: text-white
+- **highlight**: text-red-500
+
+- **dark background**: bg-zinc-700
+- **light background**: bg-gray-900
+- **overlay**: bg-gray-600
+- **input**: bg-zinc-900
+- **shadow**: gray-400
+
 ## License
 
 re:scheduled is licensed under the GNU Affero General Public License, Version 3.
\ No newline at end of file
-- 
GitLab