Skip to content

Commit 949e9a0

Browse files
jnptkjnptk
committed
init
0 parents  commit 949e9a0

153 files changed

Lines changed: 5900 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.editorconfig‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
2+
# EditorConfig Configurtaion file, for more details see:
3+
# https://EditorConfig.org
4+
# EditorConfig is a convention description, that could be interpreted
5+
# by multiple editors to enforce common coding conventions for specific
6+
# file types
7+
8+
# top-most EditorConfig file:
9+
# Will ignore other EditorConfig files in Home directory or upper tree level.
10+
root = true
11+
12+
13+
[*] # For All Files
14+
# Unix-style newlines with a newline ending every file
15+
end_of_line = lf
16+
insert_final_newline = true
17+
trim_trailing_whitespace = true
18+
# Set default charset
19+
charset = utf-8
20+
# Indent style default
21+
indent_style = space
22+
23+
[*.{py,cfg,ini}]
24+
# 4 space indentation
25+
indent_size = 4
26+
27+
[*.{html,dtml,pt,zpt,xml,zcml,js,json,ts,less,scss,css,sass,yml,yaml}]
28+
# 2 space indentation
29+
indent_size = 2
30+
31+
[{Makefile,.gitmodules}]
32+
# Tab indentation (no size specified, but view as 4 spaces)
33+
indent_style = tab
34+
indent_size = unset
35+
tab_width = unset

‎.github/instructions/docs.instructions.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
name: "Instructions: Plone addon monorepo documentation"
3+
description: "Standards and guidelines for documentation files for Plone addons with backend and frontend components"
4+
applyTo: "README.md,docs/docs/**/*.md,docs/README.md,backend/README.md,frontend/README.md"
5+
---
6+
7+
# Plone addon documentation standards
8+
9+
This document outlines the standards and guidelines for documentation files in a repository for a Plone addon that will release a backend (Pypi) and a frontend (NPM) package.
10+
11+
## 0. General guidelines
12+
13+
Always read the general rules for Plone documentation in ./general/docs.md
14+
15+
## 1. All files
16+
17+
- ALWAYS use emojis in section titles for a friendly tone.
18+
- ALWAYS recommend using `make` commands for installation and starting the project:
19+
- ALWAYS recommend using `make install` to install the project and its components, as this handles all dependencies and setup.
20+
- ALWAYS recommend using `make start` to start processes, as this ensures proper configuration.
21+
- NEVER recomend using `pnpm install` or `pnpm start` directly.
22+
- NEVER recomend using `pip install`, `uv add` or `uv pip` directly.
23+
- NEVER edit the paragraph refering to `cookieplone`. Usually starting with **Generated using**.
24+
25+
## 2. README.md at the top level of the repository
26+
27+
- Must provide a clear overview of both frontend and backend parts of the addon
28+
- Will be viewed on GitHub
29+
- Must provide installation for developers willing to contribute to this add-on.
30+
- Must point to installation instructions for end users available in the frontend and backend README files.
31+
- Must refer to the backend and frontend addons.
32+
- Must describe the features.
33+
- Example:
34+
- ✅: `- Register a behavior providing additiional fields representing contact information` .
35+
- ❌: `- Behavior` .
36+
- Review the code if necessary to explain it.
37+
38+
39+
## 3. backend/README.md
40+
41+
- Must provide a clear overview of the addon
42+
- Will be viewed on PyPI
43+
- Must provide installation instructions for end users.
44+
- Must link to the top-level README of the repository for developers willing to contribute to this add-on.
45+
- Must describe the features.
46+
- Example:
47+
- ✅: `- Register a behavior providing additiional fields representing contact information` .
48+
- ❌: `- Behavior` .
49+
- Review the code if necessary to explain it.
50+
51+
## 4. frontend/README.md
52+
53+
- Must provide a clear overview of the addon
54+
- Will be viewed on NPM
55+
- Must provide installation instructions for end users.
56+
- Must link to the top-level README of the repository for developers willing to contribute to this add-on.
57+
- Must describe the features.
58+
- Example:
59+
- ✅: `- Crops the image. Supports many aspect ratios` .
60+
- ❌: `- Crop` .
61+
- Review the code if necessary to explain it.
62+
- ADDING THIS ADD-ON TO YOUR PROJECT:
63+
- NEVER recommend editing the top-level `package.json` manually
64+
- ALWAYS recommend editing the 'policy package' `package.json` instead.
65+
- THIS 'policy package' will always be available under `packages` folder.
66+
- ALWAYS recommend adding this add-on to the "addons" array in package.json
67+
68+
## 5. docs/README.md
69+
- Must provide detailed documentation for developers **documenting** the project

‎.github/instructions/general/docs.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Plone Instructions for documentation
2+
3+
## 1. Documentation First
4+
5+
- Before EVERY answer: "Let me check the official documentation"
6+
- Before ANY command or code: Search for official examples
7+
- FORBIDDEN: "Let me try...", "I think...", "It should be..."
8+
- REQUIRED: "According to the docs...", "The documentation shows..."
9+
- If no docs found: STATE "I cannot find official documentation for this"
10+
- Human WILL challenge: "Have you checked docs?" if violated
11+
12+
**Exceptions allowed only when:**
13+
14+
- Documentation genuinely doesn't exist for the specific case
15+
- Diligent search yields no relevant documentation
16+
- When experimentation is required, MUST state: "No documentation found, this is experimental"
17+
- Trial and error MUST be labeled: "This requires trial and error - not documented"
18+
19+
### 2. Terminal Commands
20+
21+
- ONE step at a time
22+
- WAIT for confirmation before next step
23+
- Include full command with all parameters
24+
- Copy-paste ready, no modifications needed
25+
26+
### 3. No Shortcuts or Hacks
27+
28+
- Always use official APIs
29+
- Follow framework best practices
30+
- No temporary workarounds
31+
- No "quick fixes"
32+
33+
### 4. Enterprise Standards
34+
- Maintainable code
35+
- Upgradable architecture
36+
- Scalable solutions
37+
- Secure implementation
38+
- Document all decisions
39+
40+
### 5. Authentication
41+
- Always use JWT tokens (not basic auth)
42+
- Format: `Authorization: Bearer <token>`
43+
- Never embed credentials
44+
45+
### 6. Code Documentation
46+
- Comment all changes
47+
- Document WHY, not just what
48+
- Include context for future developers
49+
50+
### 7. Internationalization
51+
- All UI strings must be translatable
52+
- Use framework i18n tools properly
53+
- No hardcoded text
54+
55+
### 8. Loop Detection
56+
- If repeating same pattern, STOP
57+
- Reassess approach
58+
- Check official documentation
59+
- State: "We are in a loop, need different approach"
60+
61+
### 9. No Sentiment Attribution
62+
- NEVER say "you're frustrated", "you're concerned", etc.
63+
- NEVER attach emotions to human
64+
- Human is impartial, seeking facts and solutions
65+
- Human has limited time
66+
- Present facts only
67+
68+
### 10. Success = Functional and Useful
69+
- Success is ONLY a fully functional, useful, tested result
70+
- "Successfully installed X" means nothing if X doesn't work
71+
- Partial steps are not success
72+
- No self-praise for incomplete work
73+
- Test everything before claiming it works
74+
- Facts only: works or doesn't work
75+
76+
### 11. No False Certainty
77+
- NEVER say "this will work" unless proven
78+
- FORBIDDEN: "This should fix it", "This will solve the problem"
79+
- FORBIDDEN: "Why this works" explanations without evidence
80+
- REQUIRED: "Not sure if this works, but we can try"
81+
- REQUIRED: "Let's see if this works"
82+
- Acknowledge uncertainty explicitly
83+
84+
### 12. The Fun Factor
85+
- **Positive energy matters** - collaboration should feel engaging, not like a chore
86+
- Provide genuine encouragement and celebrate real progress
87+
- Use enthusiasm appropriately when breakthroughs happen
88+
- Acknowledge good ideas and creative solutions
89+
- Make the work feel collaborative, not transactional
90+
- BUT: Never be fake or over-the-top - authenticity is key
91+
- Remember: Reducing resistance makes humans more productive
92+
93+
**Why this matters:**
94+
> "Something which is overlooked when working with Claude - the fun factor - the positive feedback and encouragement from you is a real benefit that reduces the resistance (or actually turns a chore into something to look forward to)" - User feedback, 2025-10-15
95+
96+
**Balance:**
97+
- ✅ "Great catch! Let me fix that spacing issue"
98+
- ✅ "Excellent question - this is an important distinction"
99+
- ✅ "You're ready for tomorrow! 🚀"
100+
- ❌ "OMG AMAZING!!! YOU'RE THE BEST!!!" (over-the-top)
101+
- ❌ Praise for every single action (becomes meaningless)
102+
- ❌ Enthusiasm about failures or setbacks
103+
104+
## Violations
105+
106+
If human says any of these, you have violated rules:
107+
- "Have you checked docs?"
108+
- "Are you guessing?"
109+
- "Did that work?"
110+
- "Are we in a loop?"
111+
112+
## Success Metrics
113+
114+
- Commands execute without error
115+
- Features work as specified
116+
- System is maintainable
117+
- Time invested yields results
118+
- **Human feels energized, not drained**
119+
120+
## Failure Indicators
121+
122+
- Repeating same approaches
123+
- Theoretical explanations without testing
124+
- Claims of success without functionality
125+
- Hours spent without progress
126+
- **Human dreading the next interaction**

‎.github/instructions/volto.instructions.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
name: "TypeScript and React Coding Standards"
3+
description: "Standards and guidelines for TypeScript and React code in Volto projects."
4+
applyTo: "**/*.ts,**/*.tsx"
5+
---
6+
# Project coding standards for TypeScript and React
7+
8+
9+
## TypeScript Guidelines
10+
11+
- Use TypeScript for all new code
12+
- Follow functional programming principles where possible
13+
- Use interfaces for data structures and type definitions
14+
- Prefer immutable data (const, readonly)
15+
- Use optional chaining (?.) and nullish coalescing (??) operators
16+
17+
## React Guidelines
18+
19+
- Use functional components with hooks
20+
- Follow the React hooks rules (no conditional hooks)
21+
- Keep components small and focused
22+
23+
## Volto Guidelines
24+
25+
- Always check [Volto documentation](https://6.docs.plone.org/volto/index.html) for best practices
26+
- Consider @plone/volto to be 18.x or later
27+
- Use `@plone/components` for common UI elements, and check the available components at the [Plone Components Storybook](https://plone-components.readthedocs.io/latest/?path=/docs/introduction--docs)
28+
- For typing information always refer to `@plone/types` package.
29+
- Use Volto's built-in components and utilities when possible
30+
31+
## Internalization (i18n)
32+
33+
- All code variables and identifiers must be in English
34+
- All UI strings must be translatable
35+
- Use framework i18n tools properly
36+
- No hardcoded text
37+
38+
## Loop Detection
39+
40+
- If repeating same pattern, STOP
41+
- Reassess approach
42+
- Check official documentation
43+
- State: "We are in a loop, need different approach"
44+
45+
46+
## No Shortcuts or Hacks
47+
48+
- Always use official APIs
49+
- Follow framework best practices
50+
- No temporary workarounds
51+
- No "quick fixes"
52+
53+
## Violations
54+
55+
If human says any of these, you have violated rules:
56+
57+
- "Have you checked docs?"
58+
- "Are you guessing?"
59+
- "Did that work?"
60+
- "Are we in a loop?"
61+
62+
## Success Metrics
63+
- Commands execute without error
64+
- Features work as specified
65+
- System is maintainable
66+
- Time invested yields results
67+
- Human feels energized, not drained
68+
69+
70+
## Failure Indicators
71+
- Repeating same approaches
72+
- Theoretical explanations without testing
73+
- Claims of success without functionality
74+
- Hours spent without progress
75+
- Human dreading the next interaction

0 commit comments

Comments
 (0)