|
| 1 | +# ProjectAtlas – Basic Instructions |
| 2 | + |
| 3 | +Welcome to the ProjectAtlas repository! This document provides step-by-step instructions for setting up, developing, and maintaining a clean, well-documented codebase for the ProjectAtlas VS Code extension. Follow these guidelines to ensure consistency, clarity, and ease of contribution. |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## 1. Repository Structure |
| 8 | + |
| 9 | +The root directory should remain uncluttered. Each major component and resource must reside in its own dedicated folder. The recommended structure is: |
| 10 | + |
| 11 | +``` |
| 12 | +/ProjectAtlas |
| 13 | +│ |
| 14 | +├── .vscode/ # VS Code workspace settings |
| 15 | +├── src/ # Extension source code (TypeScript) |
| 16 | +│ ├── extension/ # Extension activation, commands, API |
| 17 | +│ ├── webview/ # React (Vite) SPA for rendering UI |
| 18 | +│ └── symbolProviders/ # Language-specific symbol extraction |
| 19 | +├── media/ # Static assets (images, icons, CSS) |
| 20 | +├── docs/ # Documentation files |
| 21 | +│ ├── basic_instructions.md |
| 22 | +│ ├── API.md |
| 23 | +│ └── architecture.md |
| 24 | +├── tests/ # Unit and integration tests |
| 25 | +├── CHANGELOG.md # Project changelog |
| 26 | +├── VERSION # Current version (e.g., 0.1.0-beta) |
| 27 | +├── package.json # Node.js project metadata |
| 28 | +├── tsconfig.json # TypeScript configuration |
| 29 | +├── vite.config.ts # Vite configuration for webview |
| 30 | +├── .gitignore # Files and folders to ignore in Git |
| 31 | +├── README.md # Project overview and quick start |
| 32 | +└── LICENSE # Open source license (MIT) |
| 33 | +``` |
| 34 | + |
| 35 | +--- |
| 36 | + |
| 37 | +## 2. Setting Up the Project |
| 38 | + |
| 39 | +1. **Clone the Repository:** |
| 40 | + ``` |
| 41 | + git clone https://github.com/your-org/ProjectAtlas.git |
| 42 | + cd ProjectAtlas |
| 43 | + ``` |
| 44 | + |
| 45 | +2. **Install Dependencies:** |
| 46 | + ``` |
| 47 | + npm install |
| 48 | + ``` |
| 49 | + |
| 50 | +3. **Build the Extension:** |
| 51 | + ``` |
| 52 | + npm run build |
| 53 | + ``` |
| 54 | + |
| 55 | +4. **Open in VS Code:** |
| 56 | + - Launch VS Code in the project directory. |
| 57 | + - Press `F5` to open a new Extension Development Host window. |
| 58 | + |
| 59 | +--- |
| 60 | + |
| 61 | +## 3. Coding Standards |
| 62 | + |
| 63 | +- **TypeScript Only:** All source code must be written in TypeScript. |
| 64 | +- **Component Placement:** Each module/component must be placed in its relevant directory. |
| 65 | +- **Commenting:** |
| 66 | + - Every file should begin with a brief comment describing its purpose. |
| 67 | + - All functions, classes, and significant code blocks must have descriptive comments explaining their logic and usage. |
| 68 | +- **Naming:** Use clear, descriptive, and consistent names for files, variables, and functions. |
| 69 | +- **Imports:** Prefer absolute imports based on the project root for clarity. |
| 70 | +- **Formatting:** Follow Prettier and ESLint rules for formatting and linting. |
| 71 | + |
| 72 | +--- |
| 73 | + |
| 74 | +## 4. Documentation |
| 75 | + |
| 76 | +- **README.md:** |
| 77 | + - Overview, features, installation, usage, and contribution guidelines. |
| 78 | +- **docs/basic_instructions.md:** |
| 79 | + - This file, providing setup and contribution basics. |
| 80 | +- **docs/API.md:** |
| 81 | + - Detailed API documentation for extension commands, settings, and message passing. |
| 82 | +- **docs/architecture.md:** |
| 83 | + - High-level and low-level architectural diagrams and explanations. |
| 84 | +- **CHANGELOG.md:** |
| 85 | + - Every release must be documented with version, date, and changes. |
| 86 | +- **VERSION:** |
| 87 | + - A single line with the current release version (e.g., `0.1.0-beta`). |
| 88 | + |
| 89 | +--- |
| 90 | + |
| 91 | +## 5. Extension Accessibility & Usage |
| 92 | + |
| 93 | +- The extension must be discoverable via the VS Code command palette as "ProjectAtlas: Open". |
| 94 | +- All features (Markdown/Mermaid/YAML/JSON/symbol graphs) should be accessible from the main UI. |
| 95 | +- No feature should require manual configuration beyond initial install. |
| 96 | +- The extension must work out of the box on Windows, macOS, and Linux. |
| 97 | + |
| 98 | +--- |
| 99 | + |
| 100 | +## 6. Contribution Guidelines |
| 101 | + |
| 102 | +- Fork the repository and create a feature branch for your changes. |
| 103 | +- Write clear, well-commented code. |
| 104 | +- Update documentation and changelog for every user-facing or internal change. |
| 105 | +- Ensure all tests pass before submitting a pull request. |
| 106 | +- Reviewers will check for code clarity, documentation, and adherence to the project structure. |
| 107 | + |
| 108 | +--- |
| 109 | + |
| 110 | +## 7. Versioning |
| 111 | + |
| 112 | +- Follow [Semantic Versioning](https://semver.org/). |
| 113 | +- The initial release is `0.1.0-beta`, as recorded in the VERSION file and CHANGELOG.md. |
| 114 | + |
| 115 | +--- |
| 116 | + |
| 117 | +## 8. Changelog Example (CHANGELOG.md) |
| 118 | + |
| 119 | +``` |
| 120 | +## [0.1.0-beta] - 2025-08-13 |
| 121 | +### Added |
| 122 | +- Initial beta release of ProjectAtlas |
| 123 | +- Live preview for Markdown, Mermaid, YAML/JSON workflows |
| 124 | +- Directory and dependency graph visualisation |
| 125 | +- Symbol and call-graph extraction for TypeScript/JavaScript |
| 126 | +- Extensible architecture for future language support |
| 127 | +``` |
| 128 | + |
| 129 | +--- |
| 130 | + |
| 131 | +## 9. Best Practices |
| 132 | + |
| 133 | +- Keep the root directory clean—no stray files or scripts. |
| 134 | +- Place all assets, tests, and docs in their respective folders. |
| 135 | +- Use meaningful commit messages. |
| 136 | +- Maintain up-to-date documentation and changelog. |
| 137 | +- Prioritize code readability and maintainability. |
| 138 | + |
| 139 | +--- |
| 140 | + |
| 141 | +By following these instructions, you will help ensure that ProjectAtlas remains a robust, accessible, and well-maintained open-source project. |
0 commit comments