mirror of
https://github.com/JuliaFEM/JuliaFEM.jl.git
synced 2026-09-22 18:52:16 +00:00
Jukka Aho
626266c990
**Three Manuals for Three Audiences:** 1. **User Manual** (docs/user/) - "Just Get It Done" - For end users, engineers, students - Simple, practical, step-by-step - Quick start, tutorials, examples, troubleshooting - Philosophy: Show me how to solve my problem 2. **Contributor Manual** (docs/contributor/) - "Show Me the Code" - For developers, contributors, advanced users - Technical, detailed, design rationale - Testing, architecture, performance, CI/CD - Philosophy: Explain HOW and WHY 3. **The JuliaFEM Book** (docs/book/) - "Let Me Show You How I Think" - For researchers, theory nerds, and Jukka - Comprehensive, educational, opinionated, personal - Math foundations, design philosophy, history, research - Philosophy: Mix theory, code, and personal experience **Reorganization:** - Moved: TESTING_PHILOSOPHY.md → contributor/testing_philosophy.md - Moved: STATUS.md → contributor/status.md - Moved: TEST_FIXES_NEEDED.md → contributor/test_fixes_needed.md - Moved: lagrange_basis_functions.md → book/lagrange_basis_functions.md - Moved: benchmarks/ → book/benchmarks/ - Created: docs/README.md (main index explaining structure) - Created: README.md in each section explaining audience and contents - Updated: All references in scripts and source files **Naming:** All docs now lowercase (testing_philosophy not TESTING_PHILOSOPHY) **Benefits:** - Clear separation of concerns - Users don't get overwhelmed with implementation details - Contributors get technical depth - Book preserves deep theory and personal insights - Each manual optimized for its audience **Next:** Populate each section with appropriate content
54 lines
1.7 KiB
Markdown
54 lines
1.7 KiB
Markdown
# JuliaFEM Contributor Manual
|
|
|
|
**Audience:** Developers, contributors, advanced users who want to extend or modify JuliaFEM.
|
|
|
|
This manual is **technical and detailed** - it explains HOW the code works and WHY we made certain design choices.
|
|
|
|
## What's Here
|
|
|
|
- **Testing Philosophy:** How and why we test
|
|
- **Code Style:** Conventions and best practices
|
|
- **Architecture:** Module structure, data flow, key abstractions
|
|
- **Performance:** Zero-allocation design, profiling, benchmarking
|
|
- **Adding Elements:** How to implement new element types
|
|
- **CI/CD:** Continuous integration, releases, versioning
|
|
- **Git Workflow:** Branching, commits, pull requests
|
|
|
|
## What's NOT Here
|
|
|
|
- User tutorials (see `docs/user/` for that)
|
|
- Deep mathematical theory (see `docs/book/` for that)
|
|
- "How do I solve problem X?" (that's user docs)
|
|
|
|
## Philosophy
|
|
|
|
**"Show me the code AND tell me why."**
|
|
|
|
We assume you:
|
|
- Know Julia reasonably well
|
|
- Understand FEM basics
|
|
- Want to add features or fix bugs
|
|
- Care about performance and correctness
|
|
- Need to understand design rationale
|
|
|
|
## Before Contributing
|
|
|
|
1. Read [Testing Philosophy](testing_philosophy.md)
|
|
2. Understand [Architecture](architecture.md)
|
|
3. Follow [Code Style](code_style.md)
|
|
4. Check [Performance Guidelines](performance.md)
|
|
5. Review [Git Workflow](git_workflow.md)
|
|
|
|
## Key Principles
|
|
|
|
- **Type stability:** No `Any`, no `Dict` without types
|
|
- **Zero allocations:** Hot paths should allocate nothing
|
|
- **Immutability:** Prefer `struct` over `mutable struct`
|
|
- **Composition:** Use tuples and free functions, not OOP hierarchies
|
|
- **Explicit:** No magic, user knows what happens
|
|
- **Test first:** Write tests before fixing bugs
|
|
|
|
---
|
|
|
|
**Start here:** [Testing Philosophy](testing_philosophy.md) | [Architecture Overview](architecture.md)
|