Contributor Guide & Contribution Priorities

Priorities of Contribution #

FleshNote is an open-source project maintained with deliberate architectural care. To make the biggest impact without wasting your development time, please review our 3 Tiers of Contribution Priorities:

Areas where we actively need community assistance:

• UI Localization: Translating UI strings in src/renderer/src/locales/*.json for missing or incomplete languages (e.g. German, French, Japanese, Spanish).
• Language-Specific NLP Refining: Improving lemmatization rules, stopword lists, and synonym dictionaries in backend/stopwords.json and backend/nltk_manager.py.
• 5-Senses Sensory Vocabulary Lexicons: Expanding language-specific synset taxonomies for The Janitor so non-English prose accurately detects olfactory, auditory, tactile, gustatory, and visual cues.
• Language-Specific Name Databases: Contributing phonotactic n-gram tables and historical/cultural name pools for the Markov character name generator.
• Place Name Generator Linguistic Parsing: Refining the place name questionnaire generator so each language correctly inflects adjectives, prefixes, compound nouns, and agglutinative case endings (e.g. Hungarian vowel harmony, Polish case suffixes, German noun compounding).

• Fixing context menu clipping or coordinate errors on ultra-wide or high-DPI displays.
• Resolving keyboard focus capture bugs when transitioning between TipTap and popup modals.
• Optimizing debounced scans (e.g., dead-link auto-scrubbing) for massive manuscripts (>150,000 words).
• Cross-platform packaging quirks on Linux (Flatpak/Wayland) or macOS Apple Silicon.

The Anti-Bloat Policy & Entity Interdependence #

While FleshNote boasts a deep, heavy-duty feature set, we actively limit the addition of new features to keep the application focused, performant, and clutter-free:

1. No Feature Duplication: If an existing feature (such as Quick Notes, Lore Entity Categories, or Annotations) already solves a problem, introducing a new dedicated button or subsystem will be rejected to avoid bloat.
2. Tightly Interwoven Entity Graph: Entities in FleshNote are not isolated database rows. Modifying or expanding entity schemas has a cascading effect across:
   • Inline TipTap marks ({{char:ID|Name}} syntax and live DOM spans).
   • Chapter appearance tracking and sensory analysis matrices.
   • World History timelines and custom calendar age calculators.
   • Plot Planner timeline blocks and turning point links.
   • Epistemic knowledge query resolution (POV filtering vs Author view).
   • Multi-device Hybrid Logical Clock (HLC) sync and field-level LWW change logs.
3. Mandatory RFC Discussion: Any proposed new feature or structural modification to existing features must be discussed and approved in a GitHub Issue RFC first before writing code. Unsolicited PRs introducing large new feature panels will be closed.

Development Workflow #

Ready to contribute? Follow this step-by-step contribution flow:

# 1. Fork the repo and create your topic branch
git checkout -b i18n/polish-sensory-lexicon
# or: git checkout -b fix/editor-context-menu-bounds

# 2. Make your focused changes and verify syntax
npm run lint
python -m py_compile backend/routes/yourfile.py

# 3. Commit with concise semantic commit messages
git commit -m "i18n: add Polish sensory vocabulary synsets for Janitor"

# 4. Push to your fork and open a Pull Request
git push origin i18n/polish-sensory-lexicon

Pull Request Quality Checklist #

Before submitting your Pull Request, ensure:

• ✓ No browser native alert boxes (alert() / confirm()) are used.
• ✓ All newly added CSS uses CSS Logical Properties (e.g. inset-inline-start instead of left) to maintain RTL support.
• ✓ Any new database columns are reflected in both backend/db_setup.py and the appropriate route Pydantic models.
• ✓ Documentation in backend/docs/ and the website docs are updated to match your changes.