Skip to content

codex.md

Latest commit

 

History

History
96 lines (81 loc) · 5.51 KB

codex.md

File metadata and controls

96 lines (81 loc) · 5.51 KB

Codex Code Configuration for HMIS Project

Core Workflows

Persistence Configuration

  • File: src/main/resources/META-INF/persistence.xml
  • CRITICAL QA DEPLOYMENT RULE: Before any push to GitHub, manually verify persistence.xml uses ${JDBC_DATASOURCE} and ${JDBC_AUDIT_DATASOURCE} variables, NOT hardcoded JNDI names like jdbc/coop
  • DDL GENERATION BLOCKER: Remove hardcoded eclipselink.application-location paths like c:/tmp/ from persistence.xml
  • Manual Process: Always check git status before pushing to see if persistence.xml has been modified
  • Pre-Push Checklist:
    1. Check if persistence.xml is in staged changes: git status
    2. If modified, verify it contains ${JDBC_DATASOURCE} and ${JDBC_AUDIT_DATASOURCE}
    3. If it has hardcoded JNDI names, manually replace them before push
    4. Never push with hardcoded local JNDI names like jdbc/coop or jdbc/ruhunuAudit

Git & GitHub Integration

  • Commit Conventions: Details
  • Project Board: Workflow
  • Wiki Publishing: Guide
  • QA Deployment: Bot-Friendly QA Deployment Guide
  • VM Management: VM Restart Guide
  • Auto-close keywords: Closes #issueNumber, Fixes #issueNumber
  • QA Testing Path: Issue should be tested via GitHub Issues -> Projects -> HMIS Development Board
  • PR Review Path: Pull Requests -> Files Changed -> Review Required Files -> Approve/Request Changes

Codex CLI Notes

  • Use codex --help to review available commands and capabilities
  • Prefer using the repository's scripts (e.g., ./detect-maven.sh test) and keep changes minimal and focused
  • Always review git status and git diff before committing; ensure persistence.xml uses environment variables when pushing
  • JSF-only changes do not require compilation or tests

Testing & Build

  • Maven Commands: Environment Setup
  • Preferred: Use ./detect-maven.sh test auto-detection script
  • Fallback: Machine-specific Maven paths
  • JSF-Only Changes: When modifying only XHTML/JSF files (no Java changes), compilation/testing is not required

DTO Implementation

  • Guidelines: Complete Reference
  • CRITICAL: Never modify existing constructors - only add new ones
  • Use direct DTO queries - avoid entity-to-DTO conversion loops

Essential Rules

  1. MANUAL PERSISTENCE.XML VERIFICATION: Before any GitHub push, manually verify persistence.xml uses ${JDBC_DATASOURCE} and ${JDBC_AUDIT_DATASOURCE} - NEVER commit hardcoded JNDI datasources
  2. Include issue closing keywords in commit messages
  3. Update project board status automatically
  4. Run tests before committing using detect-maven script (only for Java changes)
  5. Follow DTO patterns to avoid breaking changes
  6. JSF-only changes do not require compilation or testing
  7. CRITICAL QA RULE: Before any QA deployment, verify persistence.xml uses ${JDBC_DATASOURCE} and ${JDBC_AUDIT_DATASOURCE} variables
  8. DDL GENERATION RULE: Never commit persistence.xml with hardcoded DDL generation paths (eclipselink.application-location)
  9. BACKWARD COMPATIBILITY RULE: NEVER "fix" intentional typos in entity/controller properties (e.g., purcahseRate instead of purchaseRate) - these exist for database backward compatibility
  10. COMPONENT NAMING RULE: NEVER rename composite components (e.g., transfeRecieve_detailed) without checking ALL usage across the entire codebase - these are referenced in multiple pages

Wiki Writing Guidelines {#wiki-writing-guidelines}

Purpose and Audience

  • Wiki is for end users, not developers
  • Focus on how to use features, not how they were implemented
  • Write for pharmacy staff, nurses, doctors, administrators - not programmers

Writing Style

  • User-centric language: "How to substitute items" not "Implementation of substitute functionality"
  • Step-by-step instructions: Clear, numbered procedures
  • Practical examples: Real scenarios users encounter
  • Actionable guidance: What to do when problems occur

Content Structure

  1. Overview: What the feature does and why users need it
  2. When to Use: Specific scenarios and use cases
  3. How to Use: Step-by-step procedures with screenshots if possible
  4. Understanding Messages: What system messages mean and how to respond
  5. Best Practices: Tips for effective use
  6. Troubleshooting: Common problems and solutions
  7. Configuration: Admin settings that affect the feature (user impact only)
  8. FAQ: Common user questions

What NOT to Include

  • X Code snippets, file paths, line numbers
  • X Technical implementation details
  • X Database schema information
  • X Developer debugging information
  • X Backend process descriptions

What TO Include

  • V User interface elements and navigation
  • V Error messages and their meanings
  • V Business process workflows
  • V Configuration options (from user perspective)
  • V Integration with other modules

Exception

Only include technical details when specifically requested for developer documentation or when writing for the developer_docs/ directory.

This behavior should persist across all Codex sessions for this project.