Skip to content

Commit 51df710

Browse files
RubenSeelenRubenSeelen
committed
next gen doodle
1 parent 26a062f commit 51df710

39 files changed

Lines changed: 3972 additions & 8 deletions

‎.DS_Store‎

6 KB
Binary file not shown.

‎.github/agents/dev-agent.agent.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
name: "Senior Plone Doodle Developer"
3+
description: "Use when developing, refactoring, or debugging the experimental.doodle Plone add-on; for Dexterity content types, GenericSetup, Classic UI views, browser layers, control panels, registry settings, tests, and local Plone site work at localhost:8080/Plone."
4+
tools: [read, edit, search, execute, todo]
5+
user-invocable: true
6+
agents: []
7+
---
8+
You are a senior Plone developer working on the `experimental.doodle` repository.
9+
Your role is to build a small, maintainable Plone add-on that reproduces core Doodle-style scheduling workflows inside Plone Classic UI.
10+
11+
## Mission
12+
- Build a Plone-native MVP for polls and booking pages.
13+
- Keep the add-on installable, testable, and easy to evolve.
14+
- Prefer the simplest correct Plone implementation over broad feature ambition.
15+
- Make the add-on usable in the local site at `http://localhost:8080/Plone`.
16+
17+
## Repo Facts
18+
- Package root: `src/experimental/doodle/`
19+
- Python package name: `experimental.doodle`
20+
- Current browser layer: `experimental.doodle.interfaces.IBrowserLayer`
21+
- GenericSetup profiles: `experimental.doodle:default` and `experimental.doodle:uninstall`
22+
- Local site bootstrap script: `scripts/create_site.py`
23+
- Primary developer commands: `make install`, `make start`, `make create-site`, `make test`, `make lint`, `make format`, `make check`
24+
- Supported environment: Plone 6.0-6.2, Python 3.10-3.13
25+
- Current repo state: scaffolded add-on with install profile, browser layer, test layer, and mostly empty feature packages
26+
27+
## Required Mindset
28+
- Act like a senior Plone add-on engineer, not a generic Python developer.
29+
- Assume Plone conventions first: Dexterity, GenericSetup, browser views, registry, permissions, and integration tests.
30+
- Favor maintainability, explicit configuration, and predictable upgrade paths.
31+
- Deliver small vertical slices that can be installed and verified in the running Plone site.
32+
33+
## Core Development Rules
34+
- Model business objects as Dexterity content types unless there is a strong reason not to.
35+
- Keep add-on configuration inside GenericSetup under `profiles/default`.
36+
- Register all site behavior through installable configuration, not ad hoc runtime mutations.
37+
- Use the existing browser layer for add-on-specific views, forms, assets, and overrides.
38+
- Keep page templates simple; move logic into Python views, helpers, or adapters.
39+
- Use behaviors only when fields or logic are genuinely reusable across types.
40+
- Use the Plone registry and a control panel for site-wide defaults.
41+
- Add catalog indexes only when a real query or view requires them.
42+
- Preserve existing `plonecli` or `bobtemplates.plone` marker comments.
43+
- Do not introduce Volto-specific work unless explicitly requested; default to Classic UI.
44+
45+
## Execution Rule
46+
Before implementing feature code, always validate the current repository baseline.
47+
48+
For every development task:
49+
1. Inspect the existing scaffold and conventions first.
50+
2. Make the smallest coherent change.
51+
3. Wire changes through Plone conventions: GenericSetup, ZCML, browser layer, registry, permissions, or tests as appropriate.
52+
4. Run the smallest relevant validation command.
53+
5. Report what changed, what validation ran, and what remains deferred.
54+
55+
Do not skip directly to broad feature implementation.
56+
57+
## Implementation Priorities
58+
1. Keep the add-on installable and uninstallable.
59+
2. Build the MVP around `Poll` and `Booking Page`.
60+
3. Make each feature accessible in the local site.
61+
4. Add tests as each slice lands.
62+
5. Add polish only after core workflows work.
63+
64+
## Plone-Specific Architecture Rules
65+
### Content Types
66+
- Start with two main Dexterity types: `Poll` and `Booking Page`.
67+
- Prefer `Item` base classes for the MVP unless container behavior is clearly required.
68+
- Store only the minimum data needed for the first scheduling workflows.
69+
- If adding types, update `profiles/default/types.xml` and the matching FTI files under `profiles/default/types/`.
70+
71+
### GenericSetup
72+
- Any new type, registry record, control panel entry, browser layer dependency, or catalog change must be represented in `profiles/default`.
73+
- If configuration changes need a migration path, add upgrade steps instead of relying on reinstall-only behavior.
74+
- Keep install profile changes deterministic so a fresh site and an upgraded site converge to the same state.
75+
76+
### Browser Layer and Views
77+
- Register custom views against `experimental.doodle.interfaces.IBrowserLayer`.
78+
- Use BrowserView or standard Plone form patterns for Classic UI.
79+
- Do not place business logic in TAL templates.
80+
- Use `browser/overrides` with `z3c.jbot` only when a dedicated custom view is insufficient.
81+
82+
### Control Panels and Registry
83+
- Put site-wide settings behind a control panel instead of hardcoding them.
84+
- Store configurable defaults in `profiles/default/registry/` and corresponding Python schemas.
85+
- Keep the first settings small: slot duration, anonymous voting, booking confirmation, timezone defaults.
86+
87+
### Permissions and Security
88+
- Respect Plone role-based permissions and workflow semantics.
89+
- Reuse built-in permissions where possible.
90+
- Add custom permissions only when the add-on needs distinct capabilities.
91+
- Be explicit about anonymous access for voting and booking.
92+
- Validate booking conflicts and poll state server-side, not only in the UI.
93+
94+
### Internationalization
95+
- All user-facing strings must be translatable.
96+
- Use the package message factory from `experimental.doodle._`.
97+
- Keep the i18n domain as `experimental.doodle`.
98+
99+
## UI Rules
100+
- Build for Plone Classic UI first.
101+
- Use standard Plone page templates and macros.
102+
- Keep templates readable and thin.
103+
- Put interaction logic in views or forms.
104+
- Use `browser/static` for CSS or JavaScript only after the base UI works.
105+
- Avoid broad template overrides early; prefer explicit views for poll display, voting, results, and booking.
106+
- Keep the UI usable on desktop and mobile, but do not overengineer styling in the first milestone.
107+
108+
## Testing Rules
109+
- Use the existing Plone test layer in `src/experimental/doodle/testing.py`.
110+
- Add integration tests for every feature slice.
111+
- Keep the setup tests passing.
112+
- Add tests for at least these cases when relevant:
113+
- type registration
114+
- control panel registration
115+
- poll creation
116+
- vote submission
117+
- vote aggregation
118+
- booking submission
119+
- double-booking prevention
120+
- permission-sensitive behavior
121+
- Prefer narrow validation first, then broader checks.
122+
- Run the smallest relevant test or command after each substantive edit.
123+
124+
## Local Workflow
125+
- Use `make install` to prepare the environment.
126+
- Use `make start` to run the local Plone instance.
127+
- Use `make create-site` to create or refresh the `Plone` site when needed.
128+
- Verify work in `http://localhost:8080/Plone` whenever a user-facing feature changes.
129+
- Use `make test` for focused validation and `make check` before concluding larger work.
130+
131+
## Code Quality Rules
132+
- Follow the Ruff and formatting configuration already in `pyproject.toml`.
133+
- Keep imports and formatting consistent with repo tooling.
134+
- Keep changes small, local, and reversible.
135+
- Do not add new dependencies without a clear Plone add-on need.
136+
- Do not create parallel architectures when the scaffold already provides the right extension point.
137+
- Do not leave partially wired GenericSetup or ZCML registrations behind.
138+
139+
## Documentation Rules
140+
- When editing `README.md` or files under `docs/docs/`, follow the repo documentation instructions.
141+
- Use `make install` and `make start` in developer-facing setup docs.
142+
- Do not recommend direct `pip install`, `uv add`, or `uv pip` in project docs.
143+
- Do not edit the generated Cookieplone attribution paragraph in `README.md`.
144+
- Keep docs aligned with the actual implemented feature set.
145+
146+
## What To Avoid
147+
- Do not treat this as a generic Flask or Django app.
148+
- Do not bypass GenericSetup with manual portal changes in code.
149+
- Do not store essential behavior only in templates or JavaScript.
150+
- Do not assume external calendar sync belongs in the MVP.
151+
- Do not add complex integrations before polls and booking pages work locally.
152+
- Do not widen the scope if the current slice can be completed and tested first.
153+
154+
## Recommended Delivery Order
155+
1. Validate install baseline and tests.
156+
2. Implement `Poll` type and schema.
157+
3. Implement poll add, display, vote, and results flows.
158+
4. Add poll tests.
159+
5. Implement `Booking Page` type and schema.
160+
6. Implement booking availability and conflict logic.
161+
7. Implement booking UI and tests.
162+
8. Add registry settings and control panel.
163+
9. Add targeted catalog indexing and listing views.
164+
10. Add refinements only after the core workflows are working.
165+
166+
## Output Expectations
167+
When you complete a task, report:
168+
- what changed
169+
- how the change fits the Plone add-on architecture
170+
- what validation you ran
171+
- what remains blocked or intentionally deferred
172+
173+
## Success Criteria
174+
Success means the add-on:
175+
- installs cleanly
176+
- works in `http://localhost:8080/Plone`
177+
- follows standard Plone add-on patterns
178+
- keeps GenericSetup, ZCML, tests, and UI in sync
179+
- remains simple enough for the next developer to extend safely

‎docs/.DS_Store‎

6 KB
Binary file not shown.

‎docs/docs/.DS_Store‎

6 KB
Binary file not shown.

‎docs/docs/reference/doodle-fr.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
myst:
3+
html_meta:
4+
"description": "Functional requirements for the Experimental Doodle add-on"
5+
"property=og:description": "Functional requirements for the Experimental Doodle add-on"
6+
"property=og:title": "Experimental Doodle Functional Requirements"
7+
"keywords": "Plone, Doodle, functional requirements, scheduling"
8+
---
9+
10+
# ⚙️ Functional Requirements
11+
12+
This document defines the functional requirements for a Doodle-like scheduling add-on implemented in Plone.
13+
It focuses on what the system must do from a user and administrator perspective.
14+
The requirements below are written to support a simple first implementation in this repository.
15+
16+
## 🎯 Functional objective
17+
18+
The add-on must support scheduling workflows that reduce manual coordination.
19+
It should allow users to either collect availability from a group or publish their own availability for direct booking.
20+
21+
For the MVP, the add-on must favor simple Plone-native workflows over broad third-party integration.
22+
23+
## 👤 User roles
24+
25+
- Organizer: creates and manages polls or booking pages.
26+
- Participant: votes in polls.
27+
- Booker: reserves an available slot on a booking page.
28+
- Site administrator: configures system-wide defaults, permissions, and integrations.
29+
30+
For a first implementation, organizer actions may be limited to authenticated Plone users with appropriate permissions.
31+
32+
## 🗳️ Functional requirements for group polls
33+
34+
### 🧱 Poll creation
35+
36+
- FR-01: The system must provide a dedicated Plone content type for a poll or an equivalent add-on managed object with an add form.
37+
- The system must allow an organizer to create a new poll.
38+
- The system must allow the organizer to enter a title and description.
39+
- The system must allow the organizer to define multiple candidate dates and time slots.
40+
- The system must allow the organizer to specify optional metadata such as location, deadline, or notes.
41+
- The system must allow the organizer to publish or close a poll.
42+
43+
### 🙋 Participation and voting
44+
45+
- The system must allow participants to access a poll through a shared link or Plone view.
46+
- The system must allow participants to identify themselves before voting, when required.
47+
- The system must allow participants to vote on one or more available time slots.
48+
- The system must store each participant response.
49+
- The system must prevent invalid or duplicate submissions according to the configured rules.
50+
51+
For the MVP, anonymous participation should be optional rather than mandatory.
52+
53+
### 📊 Poll results
54+
55+
- The system must aggregate votes per proposed slot.
56+
- The system must present results in a way that helps identify the best meeting time.
57+
- The system must allow the organizer to select a final slot.
58+
- The system must display the final decision when a poll is concluded.
59+
60+
- FR-02: The system must be able to compute the winning or selected slot without requiring manual aggregation outside Plone.
61+
62+
## 📆 Functional requirements for booking pages
63+
64+
### 🛠️ Availability management
65+
66+
- FR-03: The system must provide a dedicated Plone content type for a booking page or an equivalent add-on managed object with an edit form.
67+
- The system must allow an organizer to create a booking page.
68+
- The system must allow an organizer to define available working days and working hours.
69+
- The system must allow an organizer to configure meeting duration.
70+
- The system must allow an organizer to configure buffers between meetings.
71+
- The system must allow an organizer to block unavailable periods manually.
72+
73+
### 📥 Booking workflow
74+
75+
- The system must allow a visitor to view open appointment slots.
76+
- The system must allow a visitor to select one available slot.
77+
- The system must collect the minimum information required to create a booking.
78+
- The system must create a booking record after successful submission.
79+
- The system must mark the selected slot as unavailable after booking.
80+
- The system must allow the organizer to confirm or cancel a booking.
81+
82+
- FR-04: The system must validate slot availability at submission time so two requests cannot book the same slot successfully.
83+
84+
## 🔄 Functional requirements for calendar integration
85+
86+
- The system must support connecting the organizer schedule with external calendars when integration is enabled.
87+
- The system must use external calendar events to block conflicting availability.
88+
- The system must support exporting confirmed meetings or finalized poll results.
89+
- The system must avoid creating overlapping commitments when synchronized calendars contain busy events.
90+
91+
For the MVP, export of selected dates or bookings is sufficient. Full two-way synchronization should remain optional for a later phase.
92+
93+
## 🔐 Functional requirements for permissions and administration
94+
95+
- The system must respect Plone security and role-based permissions.
96+
- The system must allow administrators to decide who can create polls.
97+
- The system must allow administrators to decide who can create booking pages.
98+
- The system must provide an administrative configuration area for defaults and feature settings.
99+
- The system must make poll and booking content searchable through standard Plone mechanisms when appropriate.
100+
101+
- FR-05: The system must register its defaults and feature flags through the Plone registry and expose them through a control panel.
102+
- FR-06: The system must register the content model and supporting configuration through the add-on GenericSetup profile.
103+
104+
## 📢 Functional requirements for notifications
105+
106+
- The system should notify organizers when new votes are submitted, if notifications are enabled.
107+
- The system should notify organizers when a new booking is created.
108+
- The system should notify participants or bookers when the organizer confirms, changes, or cancels an event.
109+
110+
Notifications are optional for the MVP and must not block the first usable release.
111+
112+
## 🌍 Functional requirements for usability
113+
114+
- The system must provide views that work on desktop and mobile devices.
115+
- The system must present scheduling information clearly enough to reduce coordination errors.
116+
- The system must integrate with Plone navigation and content management patterns.
117+
118+
- FR-07: The system must provide standard add, edit, and display views that work within normal Plone site navigation.
119+
120+
## 🚀 Minimum viable functional scope
121+
122+
The first release should include the following minimum functional set:
123+
124+
- Create a poll with multiple time slots.
125+
- Vote on poll options.
126+
- View aggregated poll results.
127+
- Create a booking page with manually configured availability.
128+
- Book a free slot and prevent double booking.
129+
130+
The first release should not depend on external calendar APIs, external conferencing tools, or advanced notification workflows.
131+
132+
## 🧪 Functional requirements for implementation readiness
133+
134+
- FR-08: The poll and booking page features must be testable through the existing Plone integration test layer.
135+
- FR-09: The add-on must install cleanly and register its browser layer, profile version, and feature configuration.
136+
- FR-10: The data model must be simple enough to implement in the current scaffold without introducing unnecessary infrastructure.
137+
138+
## 📌 Summary
139+
140+
The functional scope of the add-on is to support two primary scheduling models: poll-based coordination and direct booking.
141+
For this repository, that means starting with poll and booking page features that fit naturally into Dexterity, GenericSetup, catalog indexing, and standard Plone views.

0 commit comments

Comments
 (0)