|
1 | | -# World Domination Software - Projects Repository Guidelines |
| 1 | +# World Domination Software — Projects Repository Guidelines |
2 | 2 |
|
3 | 3 | ## Repository Role |
4 | 4 |
|
5 | 5 | - This repository (`World-Domination-Software/Projects`) is the **customer-facing hub** for all WDS projects (games, tools, hosting, and related products). |
6 | 6 | - It centralizes: |
7 | | - - High-level project descriptions and design documents (Wiki) |
| 7 | + - Application-specific documentation under `docs/applications/` |
8 | 8 | - Future project ideas and feature proposals (Discussions → Ideas category) |
9 | 9 | - Bug reports, incidents, and support tickets (Issues) |
10 | 10 | - General project discussions and community feedback (Discussions) |
11 | 11 | - The public website repository (`WDS_Website`) links to this repo from its `projects.php` page for all detailed project information and customer interaction. |
12 | 12 |
|
| 13 | +## Terminology |
| 14 | + |
| 15 | +**"wiki" in this repository refers only to the actual GitHub Wiki** at: |
| 16 | +`https://github.com/World-Domination-Software/Projects/wiki` |
| 17 | + |
| 18 | +Do **not** refer to files under `docs/` as "wiki". Do **not** create a top-level `wiki/` folder in the code repository. Any previously existing `wiki/` folder has been replaced with a stub. |
| 19 | + |
| 20 | +## Documentation Structure |
| 21 | + |
| 22 | +### docs/ — Application-specific documentation only |
| 23 | + |
| 24 | +``` |
| 25 | +docs/ |
| 26 | + README.md – Overview of the docs/ folder and its structure. |
| 27 | + INDEX.md – Table of all applications with links. |
| 28 | + applications/ |
| 29 | + <app-name>/ |
| 30 | + README.md – Landing page; links to sub-docs and public resources. |
| 31 | + Overview.md – What the application is, features, and architecture. |
| 32 | + Getting-Started.md – Installation and first-use guide. |
| 33 | + Implementation-Notes.md – Architecture, components, and development status. |
| 34 | + Gameplay.md – (Games only) Game modes, controls, and progression. |
| 35 | +``` |
| 36 | + |
| 37 | +**Rules for docs/:** |
| 38 | +1. `docs/` contains **application-specific documentation only**. |
| 39 | +2. Shared/general pages — FAQ, support, bug reporting, roadmap, shared troubleshooting — must **not** live in `docs/` unless they are app-specific. |
| 40 | +3. Every application gets its own subfolder under `docs/applications/`. |
| 41 | +4. Every application folder must contain a `README.md` as its landing page. |
| 42 | +5. Folder names must be **lowercase dash-separated** (e.g., `hostile-planets`, `game-servers-panel`). |
| 43 | + |
| 44 | +### GitHub Wiki — Shared and public-facing documentation |
| 45 | + |
| 46 | +The **actual GitHub Wiki** at `https://github.com/World-Domination-Software/Projects/wiki` is the public/shared documentation layer for: |
| 47 | +- FAQ |
| 48 | +- Shared troubleshooting |
| 49 | +- Bug reporting guidance |
| 50 | +- Support guidance |
| 51 | +- Roadmap |
| 52 | +- Community and discussions guides |
| 53 | + |
| 54 | +Do not duplicate shared content between `docs/` and the GitHub Wiki. |
| 55 | + |
13 | 56 | ## How This Repo Interacts With Others |
14 | 57 |
|
15 | 58 | - **WDS_Website** |
16 | 59 | - Lists projects and shows short summaries only. |
17 | | - - Each project row links here for wiki pages, ideas, discussions, and issue reporting. |
18 | | - - Changes to project naming, categories, or status here should be reflected in the website’s project list (and vice versa) so they stay in sync. |
| 60 | + - Each project row links here for app docs, discussions, and issue reporting. |
| 61 | + - Changes to project naming, categories, or status here should be reflected in the website's project list (and vice versa) so they stay in sync. |
19 | 62 |
|
20 | 63 | - **GSP / Agents and Other Service Repos** |
21 | 64 | - Game server panel and agent repos are internal implementation details. |
22 | | - - Customer-facing documentation, roadmaps, and issue tracking for those services should live **in this repo** (Wiki/Issues/Discussions), then link out to the underlying technical repos when necessary. |
| 65 | + - Customer-facing documentation, roadmaps, and issue tracking for those services should live **in this repo** (`docs/applications/`, Issues, Discussions), then link out to the underlying technical repos when necessary. |
23 | 66 |
|
24 | 67 | ## Guidance for AIs Working in This Repo |
25 | 68 |
|
26 | 69 | - Treat this repo as the **source of truth for customer-visible project information and planning**. |
27 | | -- When adding or modifying structures (labels, discussion categories, issue templates, wiki organization): |
| 70 | +- When adding or modifying structures (labels, discussion categories, issue templates, documentation): |
28 | 71 | - Keep terminology consistent with what the WDS website uses for project names and categories. |
29 | 72 | - Prefer adding new templates/structures over breaking existing ones that might already be in use. |
30 | 73 | - Do **not** move long-form documentation back into the website codebase; the website should point here instead. |
31 | | -- When suggesting or generating new content (issue templates, discussion prompts, wiki outlines), make it: |
| 74 | +- When suggesting or generating new content (issue templates, discussion prompts, documentation), make it: |
32 | 75 | - Professional, clear, and accessible (non-hyperbolic, but engaging). |
33 | 76 | - Organized so non-technical community members can navigate easily. |
34 | 77 |
|
35 | | -## Future Structure (for Templates and Automation) |
| 78 | +## Adding a New Application |
| 79 | + |
| 80 | +When adding a new application to this repository: |
| 81 | + |
| 82 | +1. Create a new folder: `docs/applications/<application-name>/` |
| 83 | +2. Add the following files using the templates below: |
| 84 | + - `README.md` |
| 85 | + - `Overview.md` |
| 86 | + - `Getting-Started.md` |
| 87 | + - `Implementation-Notes.md` |
| 88 | + - `Gameplay.md` *(if the application is a game)* |
| 89 | +3. Add a row to `docs/INDEX.md`. |
| 90 | +4. Update `mkdocs.yml` to include the new files in the nav if the MkDocs site is in use. |
| 91 | +5. Add a corresponding row to the applications table in the top-level `README.md`. |
| 92 | + |
| 93 | +## Application README Template |
| 94 | + |
| 95 | +Each `docs/applications/<app>/README.md` must follow this format: |
| 96 | + |
| 97 | +```markdown |
| 98 | +# Application Name |
| 99 | + |
| 100 | +Short project description. |
| 101 | + |
| 102 | +**Type:** <Game / Utility / Business Tool / etc.> | **Developer:** World Domination Software LLC |
| 103 | + |
| 104 | +## Documentation |
| 105 | +- [Overview](./Overview.md) |
| 106 | +- [Getting Started](./Getting-Started.md) |
| 107 | +- [Gameplay](./Gameplay.md) ← include only if applicable |
| 108 | +- [Implementation Notes](./Implementation-Notes.md) |
| 109 | + |
| 110 | +## Public Links |
| 111 | +- [GitHub Wiki](https://github.com/World-Domination-Software/Projects/wiki/<App-Wiki-Page>) |
| 112 | +- [Bug Reports](https://github.com/World-Domination-Software/Projects/issues) |
| 113 | +- [Discussions](https://github.com/World-Domination-Software/Projects/discussions/categories/<app-discussions-category>) |
| 114 | + |
| 115 | +## Notes |
| 116 | +This folder contains application-specific documentation only. |
| 117 | +Shared FAQ, support, roadmap, and shared troubleshooting are maintained in the [GitHub Wiki](https://github.com/World-Domination-Software/Projects/wiki). |
| 118 | +``` |
| 119 | + |
| 120 | +## Linking Rules |
| 121 | + |
| 122 | +- Use **relative links** for links within `docs/` (e.g., `[Overview](./Overview.md)`). |
| 123 | +- Use **full GitHub URLs** for: |
| 124 | + - The actual GitHub Wiki (e.g., `https://github.com/World-Domination-Software/Projects/wiki/...`) |
| 125 | + - Issues (e.g., `https://github.com/World-Domination-Software/Projects/issues`) |
| 126 | + - Discussions (e.g., `https://github.com/World-Domination-Software/Projects/discussions/...`) |
| 127 | +- Update all links when moving documentation files. |
| 128 | + |
| 129 | +## Automation |
36 | 130 |
|
37 | | -- This repo is expected to contain: |
38 | | - - Issue templates for bug reports, feature requests, and support. |
39 | | - - Discussion templates/categories for ideas, playtesting feedback, and devlogs. |
40 | | - - Wiki templates for per-project overview pages (summary, status, links to builds, etc.). |
| 131 | +- Issue templates for bug reports, feature requests, and support live in `.github/ISSUE_TEMPLATE/`. |
41 | 132 | - When creating new templates or automation, assume they will be: |
42 | 133 | - Linked from `projects.php` on the WDS website. |
43 | 134 | - Used by both internal staff and external community members. |
0 commit comments