235 lines
5.1 KiB
Markdown
235 lines
5.1 KiB
Markdown
# README Update Guide
|
|
|
|
**Last Updated**: 2025-01-27
|
|
**Purpose**: Guide for updating project READMEs to follow standardized template
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This guide provides instructions for updating existing project READMEs to follow the standardized template located at `.github/README_TEMPLATE.md`.
|
|
|
|
---
|
|
|
|
## Standardized Template
|
|
|
|
The template is available at: [.github/README_TEMPLATE.md](../.github/README_TEMPLATE.md)
|
|
|
|
### Key Sections
|
|
1. **Header** - Status, monorepo info, last updated
|
|
2. **Overview** - Brief project description
|
|
3. **Purpose** - Detailed purpose and goals
|
|
4. **Features** - Core and additional features
|
|
5. **Technology Stack** - Technologies used
|
|
6. **Getting Started** - Setup instructions
|
|
7. **Project Structure** - Directory structure
|
|
8. **Documentation** - Links to additional docs
|
|
9. **Related Projects** - Cross-references
|
|
10. **License** - License information
|
|
|
|
---
|
|
|
|
## Update Process
|
|
|
|
### Step 1: Review Template
|
|
1. Read the standardized template
|
|
2. Understand required sections
|
|
3. Identify optional sections for your project
|
|
|
|
### Step 2: Assess Current README
|
|
1. Review existing README
|
|
2. Identify existing content to preserve
|
|
3. Identify missing sections
|
|
4. Identify outdated information
|
|
|
|
### Step 3: Update README
|
|
1. Add header with status and metadata
|
|
2. Ensure all required sections are present
|
|
3. Update content to match template structure
|
|
4. Preserve project-specific information
|
|
5. Add cross-references to related projects
|
|
|
|
### Step 4: Verify
|
|
1. Check all links work
|
|
2. Verify code examples
|
|
3. Ensure consistency with other projects
|
|
4. Review formatting
|
|
|
|
---
|
|
|
|
## Project-Specific Updates Needed
|
|
|
|
### Active Projects (High Priority)
|
|
|
|
#### dbis_core
|
|
- [ ] Add monorepo relationship note (will be part of dbis_monorepo)
|
|
- [ ] Ensure all sections match template
|
|
- [ ] Add related projects section
|
|
- [ ] Update last updated date
|
|
|
|
#### the_order
|
|
- [ ] Add monorepo structure section (already has some)
|
|
- [ ] Ensure template compliance
|
|
- [ ] Document submodule relationships
|
|
|
|
#### smom-dbis-138
|
|
- [ ] Add deployment relationship notes (Sankofa Phoenix, loc_az_hci)
|
|
- [ ] Ensure template compliance
|
|
- [ ] Document tenant deployment model
|
|
|
|
#### Sankofa
|
|
- [ ] Add PanTel joint venture note
|
|
- [ ] Ensure template compliance
|
|
- [ ] Document platform relationships
|
|
|
|
### DeFi Projects (Medium Priority)
|
|
|
|
#### 237-combo, 27-combi, strategic, CurrenciCombo
|
|
- [ ] Add Defi-Mix-Tooling monorepo note
|
|
- [ ] Ensure template compliance
|
|
- [ ] Document relationships
|
|
|
|
### Other Projects (Lower Priority)
|
|
- [ ] Review and update as needed
|
|
- [ ] Ensure basic template compliance
|
|
- [ ] Add metadata sections
|
|
|
|
---
|
|
|
|
## Template Sections Explained
|
|
|
|
### Header Section
|
|
```markdown
|
|
# [Project Name]
|
|
|
|
**Status**: [Active/Placeholder/Archived]
|
|
**Monorepo**: [Monorepo name if applicable] / Standalone
|
|
**Last Updated**: [Date]
|
|
```
|
|
|
|
### Overview Section
|
|
- 2-3 sentences explaining what the project does
|
|
- High-level purpose
|
|
- Key value proposition
|
|
|
|
### Purpose Section
|
|
- Detailed explanation
|
|
- Goals and objectives
|
|
- Use cases
|
|
- Target users
|
|
|
|
### Features Section
|
|
- Core features (must-have)
|
|
- Additional features (nice-to-have)
|
|
- Organized by category if needed
|
|
|
|
### Technology Stack Section
|
|
- Frontend technologies (if applicable)
|
|
- Backend technologies (if applicable)
|
|
- Infrastructure (if applicable)
|
|
- Tools and frameworks
|
|
|
|
### Getting Started Section
|
|
- Prerequisites
|
|
- Installation steps
|
|
- Configuration
|
|
- Running the project
|
|
|
|
### Project Structure Section
|
|
- Directory tree (simplified)
|
|
- Key directories explained
|
|
- Code organization
|
|
|
|
### Documentation Section
|
|
- Links to additional documentation
|
|
- Architecture docs
|
|
- API docs
|
|
- Deployment guides
|
|
|
|
### Related Projects Section
|
|
- Links to related projects
|
|
- Brief description of relationship
|
|
- Integration points
|
|
|
|
---
|
|
|
|
## Examples
|
|
|
|
### Example: Monorepo Submodule
|
|
|
|
```markdown
|
|
# Project Name
|
|
|
|
**Status**: ✅ Active
|
|
**Monorepo**: Defi-Mix-Tooling (submodule)
|
|
**Last Updated**: 2025-01-27
|
|
```
|
|
|
|
### Example: Standalone Project
|
|
|
|
```markdown
|
|
# Project Name
|
|
|
|
**Status**: ✅ Active
|
|
**Monorepo**: Standalone
|
|
**Last Updated**: 2025-01-27
|
|
```
|
|
|
|
### Example: Related Projects Section
|
|
|
|
```markdown
|
|
## Related Projects
|
|
|
|
- **[dbis_core](../dbis_core/)** - Core banking system (integrates with this project)
|
|
- **[smom-dbis-138](../smom-dbis-138/)** - Blockchain infrastructure (uses this project)
|
|
- **[dbis_docs](../dbis_docs/)** - Documentation (references this project)
|
|
```
|
|
|
|
---
|
|
|
|
## Checklist
|
|
|
|
### Required Sections
|
|
- [ ] Header with status and metadata
|
|
- [ ] Overview (2-3 sentences)
|
|
- [ ] Purpose (detailed explanation)
|
|
- [ ] Features (core and additional)
|
|
- [ ] Technology Stack
|
|
- [ ] Getting Started
|
|
- [ ] Project Structure
|
|
- [ ] Documentation links
|
|
- [ ] Related Projects
|
|
- [ ] License
|
|
|
|
### Optional Sections
|
|
- [ ] Architecture diagrams
|
|
- [ ] API documentation
|
|
- [ ] Contributing guidelines
|
|
- [ ] Changelog
|
|
- [ ] Roadmap
|
|
|
|
---
|
|
|
|
## Priority Order
|
|
|
|
1. **High Priority Projects**
|
|
- dbis_core
|
|
- the_order
|
|
- smom-dbis-138
|
|
- Sankofa
|
|
|
|
2. **Medium Priority Projects**
|
|
- Defi-Mix-Tooling projects
|
|
- Web applications
|
|
- Other active projects
|
|
|
|
3. **Lower Priority Projects**
|
|
- Placeholder projects
|
|
- Documentation projects
|
|
- Utility projects
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-01-27
|
|
|