**chore: remove outdated changelog and summary documents**
- Deleted `CHANGES.md`, `CHANGES_SUMMARY.md`, `CONCURRENCY_ANALYSIS.md`, `CONCURRENCY_IMPLEMENTATION_SUMMARY.md`, and related developer documentation files. - Removed redundant or legacy content no longer aligned with the current codebase and workflows. - Updated repository to reflect streamlined documentation approach, reducing clutter and improving maintainability. **Purpose**: Simplify and declutter repository by removing obsolete documentation files, ensuring it remains focused and relevant.
This commit is contained in:
parent
0f2075ede4
commit
79df44351c
30 changed files with 343 additions and 3 deletions
153
docs/development/DOCUMENTATION_STANDARDS.md
Normal file
153
docs/development/DOCUMENTATION_STANDARDS.md
Normal file
|
|
@ -0,0 +1,153 @@
|
|||
# Documentation Standards for Brainy
|
||||
|
||||
<div align="center">
|
||||
<img src="./brainy.png" alt="Brainy Logo" width="200"/>
|
||||
</div>
|
||||
|
||||
This document outlines the documentation standards and conventions for the Brainy project, including markdown file naming conventions and troubleshooting information for common documentation issues.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Markdown File Naming Conventions](#markdown-file-naming-conventions)
|
||||
- [Documentation Troubleshooting](#documentation-troubleshooting)
|
||||
|
||||
## Markdown File Naming Conventions
|
||||
|
||||
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.
|
||||
|
||||
## Documentation Troubleshooting
|
||||
|
||||
This section covers common documentation-related issues and their solutions.
|
||||
|
||||
### Fix for "process.memoryUsage is not a function" Error in Vitest
|
||||
|
||||
#### Issue
|
||||
During test runs with Vitest, the following error was occurring:
|
||||
|
||||
```
|
||||
TypeError: process.memoryUsage is not a function
|
||||
❯ VitestTestRunner.onAfterRunSuite node_modules/vitest/dist/runners.js:150:95
|
||||
```
|
||||
|
||||
This error was happening because Vitest was trying to use `process.memoryUsage()` to log heap usage statistics, but this function was not available in the current environment.
|
||||
|
||||
#### Solution
|
||||
The issue was fixed by disabling the heap usage logging in the Vitest configuration:
|
||||
|
||||
In `vitest.config.ts`, changed:
|
||||
```typescript
|
||||
// Show test statistics
|
||||
logHeapUsage: true,
|
||||
```
|
||||
|
||||
To:
|
||||
```typescript
|
||||
// Show test statistics
|
||||
logHeapUsage: false,
|
||||
```
|
||||
|
||||
#### Explanation
|
||||
The `logHeapUsage` option in Vitest attempts to use Node.js's `process.memoryUsage()` function to track and report memory usage during test runs. However, this function might not be available in all environments, particularly in certain browser-like environments or when using specific Node.js versions or configurations.
|
||||
|
||||
By setting `logHeapUsage: false`, we prevent Vitest from attempting to call this function, which resolves the error while still allowing tests to run successfully.
|
||||
|
||||
#### Verification
|
||||
After making this change, the tests run without any unhandled errors, confirming that the issue has been resolved.
|
||||
|
||||
### Common Documentation Issues and Solutions
|
||||
|
||||
#### Issue: Inconsistent Markdown Formatting
|
||||
|
||||
**Symptoms**: Inconsistent heading levels, list formatting, or code block syntax across documentation files.
|
||||
|
||||
**Solution**:
|
||||
- Use a markdown linter to enforce consistent formatting
|
||||
- Follow the project's markdown style guide
|
||||
- Use the same heading structure across similar documents
|
||||
|
||||
#### Issue: Broken Links in Documentation
|
||||
|
||||
**Symptoms**: Links to other documentation files or sections within files don't work.
|
||||
|
||||
**Solution**:
|
||||
- Use relative links for references to other files in the repository
|
||||
- Use anchor links for references to sections within the same file
|
||||
- Regularly check for broken links, especially after moving or renaming files
|
||||
|
||||
#### Issue: Outdated Documentation
|
||||
|
||||
**Symptoms**: Documentation describes features or APIs that have changed or been removed.
|
||||
|
||||
**Solution**:
|
||||
- Update documentation as part of the same PR that changes the code
|
||||
- Add a "Last Updated" date to documentation files
|
||||
- Regularly review and update documentation
|
||||
|
||||
#### Issue: Missing Documentation
|
||||
|
||||
**Symptoms**: Features or APIs lack documentation, making them difficult to use.
|
||||
|
||||
**Solution**:
|
||||
- Require documentation for new features as part of the PR review process
|
||||
- Create documentation templates for common types of documentation
|
||||
- Identify and prioritize documentation gaps
|
||||
Loading…
Add table
Add a link
Reference in a new issue