**feat(core, docs): consolidate redundant files and improve documentation structure**
- **Storage**: Removed redundant storage implementation files from `/storage` directory while retaining necessary `baseStorage.ts`. Verified no impact on functionality with passing tests. - **Documentation**: Consolidated multiple overlapping `.md` files into a single `statistics.md` file. Added structured sections for easier reference. Applied markdown naming conventions for clarity. - **Project**: Introduced `CHANGES_SUMMARY.md` and `MARKDOWN_CONVENTIONS.md` to document changes and naming guidelines, improving project organization. Updated `demo.md` file naming for consistency. **Purpose**: Simplify the codebase by removing duplicates, enhance maintainability through consolidated and structured documentation, and improve developer experience with clear guidelines and better organization.
This commit is contained in:
parent
4389485fd7
commit
b0ba4f185d
5 changed files with 375 additions and 2 deletions
67
MARKDOWN_CONVENTIONS.md
Normal file
67
MARKDOWN_CONVENTIONS.md
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
# Markdown File Naming Conventions
|
||||
|
||||
This document outlines the naming conventions for markdown (.md) files in the Brainy project.
|
||||
|
||||
## Naming Patterns
|
||||
|
||||
Based on the current project structure, we follow these conventions for markdown files:
|
||||
|
||||
### Uppercase Naming
|
||||
|
||||
Use uppercase filenames for project-level documentation:
|
||||
|
||||
- README.md - Project overview and main documentation
|
||||
- CONTRIBUTING.md - Contribution guidelines
|
||||
- LICENSE.md - License information
|
||||
- CHANGES.md - Changelog
|
||||
- CODE_OF_CONDUCT.md - Code of conduct
|
||||
- Other project-level documentation files
|
||||
|
||||
Examples: `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`
|
||||
|
||||
### Lowercase Naming
|
||||
|
||||
Use lowercase filenames for technical documentation and implementation details:
|
||||
|
||||
- Technical guides
|
||||
- Implementation details
|
||||
- Architecture documentation
|
||||
- Specific feature documentation
|
||||
|
||||
Examples: `scalingStrategy.md`, `statistics.md`
|
||||
|
||||
## Rationale
|
||||
|
||||
This convention makes it easy to distinguish between:
|
||||
|
||||
1. Project-level documentation that applies to the entire project and is relevant to all contributors and users (uppercase)
|
||||
2. Technical documentation that focuses on specific implementation details and is primarily relevant to developers working on those features (lowercase)
|
||||
|
||||
## Recommendations
|
||||
|
||||
1. Continue using uppercase names for project-level documentation files
|
||||
2. Continue using lowercase names for technical documentation files
|
||||
3. Be consistent within each category
|
||||
4. Always use `README.md` (uppercase) for directory-level documentation
|
||||
|
||||
## Examples
|
||||
|
||||
### Project-Level Documentation (Uppercase)
|
||||
|
||||
- README.md
|
||||
- CONTRIBUTING.md
|
||||
- LICENSE.md
|
||||
- CHANGES.md
|
||||
- CODE_OF_CONDUCT.md
|
||||
- DEVELOPERS.md
|
||||
- STORAGE_TESTING.md
|
||||
- THREADING.md
|
||||
|
||||
### Technical Documentation (Lowercase)
|
||||
|
||||
- scalingStrategy.md
|
||||
- statistics.md
|
||||
- architecture.md
|
||||
- implementation-details.md
|
||||
|
||||
By following these conventions, we maintain consistency and make it easier for contributors to find the right documentation.
|
||||
Loading…
Add table
Add a link
Reference in a new issue