Skip to content

Wiki Management

Jump to bottom
jjoonleo edited this page Dec 31, 2025 · 4 revisions

Wiki Management Guide

This guide explains how to modify, create, and upload wiki documentation for the OnTime Flutter project.

📖 Overview

Our project wiki is integrated directly into the main repository using Git subtrees. This means:

  • Wiki content is stored in the docs/ folder
  • Changes are version-controlled with the main codebase
  • Documentation stays in sync with code changes
  • New developers can access docs offline

🚀 Quick Start

Prerequisites

  • Git configured with your GitHub account
  • Access to the OnTime-front repository
  • Basic knowledge of Markdown

Current Wiki Structure

docs/
├── Architecture.md      # Project structure and architecture
├── Git.md              # Git workflow and commit guidelines
├── Home.md             # Wiki homepage
└── Wiki-Management.md  # This guide

✏️ Modifying Existing Wiki Pages

1. Edit Files Locally

Navigate to the docs/ folder and edit any .md file:

# Navigate to docs folder
cd docs/

# Edit existing files with your preferred editor
code Architecture.md
# or
vim Home.md
# or
nano Git.md

2. Preview Your Changes

Use any Markdown preview tool or your IDE's built-in preview to review changes before committing.

3. Commit Changes to Main Repository

# From project root
git add docs/
git commit -m "docs: update [filename] with [brief description]"

📝 Creating New Wiki Pages

1. Create New Markdown File

# From project root
touch docs/New-Page-Name.md

2. Add Content

Use standard Markdown syntax. Here's a template:

# Page Title

Brief description of what this page covers.

## Section 1

Content here...

### Subsection

More detailed content...

## Code Examples

\```dart
// Flutter/Dart code examples
void main() {
print('Hello OnTime!');
}
\```

## Links and References

- [Internal Link](./Other-Page.md)
- [External Link](https://flutter.dev)

3. Update Navigation

If creating a major new page, consider updating Home.md to include a link to your new page.

🔄 Syncing with GitHub Wiki

Our project uses Git subtree to keep the main repository and GitHub wiki synchronized.

Push Local Changes to GitHub Wiki

After committing your documentation changes to the main repository:

# Push documentation changes to GitHub wiki
git subtree push --prefix=docs wiki master

What this does:

  • Takes all changes from the docs/ folder
  • Pushes them to the GitHub wiki repository
  • Updates the online wiki at https://github.com/DevKor-github/OnTime-front/wiki

Force push to GitHub Wiki (use with extreme caution)

Sometimes the wiki remote can get out of sync (e.g., someone edited pages directly on GitHub and you want to overwrite the wiki with your local docs/ state). In that case, you can force push — but note:

  • This rewrites the wiki repo history and can discard other people's edits.
  • Only do this if the team agrees and you’re sure your local docs/ is the desired source of truth.
  • Consider pulling first (git subtree pull --prefix=docs wiki master --squash) to avoid needing force.

git subtree push doesn’t accept --force, so you force-push by splitting and pushing the split commit:

# 0) Make sure your docs changes are committed
git status

# 1) Create a split commit containing only docs/ history
git subtree split --prefix=docs -b docs/wiki-split

# 2) Force push that split to the wiki remote
git push wiki docs/wiki-split:master --force

If you don’t want to keep the temporary branch around:

# Create the split commit SHA and force push it directly
SPLIT_SHA=$(git subtree split --prefix=docs HEAD)
git push wiki "$SPLIT_SHA":master --force-with-lease

Afterwards, it’s safe to delete the temp branch:

git branch -D docs/wiki-split

Pull Changes from GitHub Wiki

If someone edits the wiki directly on GitHub:

# Pull changes from GitHub wiki to local docs folder
git subtree pull --prefix=docs wiki master --squash

When to use this:

  • Someone edited wiki pages directly on GitHub
  • You want to sync external wiki changes to your local repository
  • Before starting major documentation work (to avoid conflicts)

Troubleshooting subtree sync

Issue: fatal: working tree has modifications. Cannot add.

git subtree pull requires a clean working tree.

git status
# then either commit or stash
git add docs/
git commit -m "docs: WIP before subtree pull"
# or
git stash -u

Issue: fatal: refusing to merge unrelated histories

This happens when your local docs/ history and the GitHub wiki repository don’t share a common subtree “join” history (often because docs/ wasn’t originally introduced via git subtree add, or the wiki was rewritten independently).

Pick one of these paths:

  1. Overwrite wiki with local docs/ (recommended if docs/ is the source of truth):
git status
git subtree split --prefix=docs -b docs/wiki-split
git push wiki docs/wiki-split:master --force-with-lease
git branch -D docs/wiki-split
  1. Import wiki into this repo (one-time) and then merge your local docs (recommended if the wiki is the source of truth):
# Backup current docs
git mv docs docs_local
git commit -m "chore(docs): backup local docs before importing wiki"

# Bring wiki content into docs/ (establishes subtree join history)
git subtree add --prefix=docs wiki master --squash

# Now manually reconcile docs_local/ -> docs/ as needed, then:
rm -rf docs_local
git add -A
git commit -m "docs: reconcile local docs with wiki import"

🔧 Advanced Workflows

Working on Documentation-Heavy Features

  1. Create a documentation branch:

    git checkout -b docs/feature-name

  2. Make your documentation changes

  3. Commit and push to main repository:

    git add docs/
git commit -m "docs: add documentation for feature-name"
git push origin docs/feature-name

  4. Create PR for review

  5. After PR merge, sync to wiki:

    git checkout main
git pull origin main
git subtree push --prefix=docs wiki master

Handling Merge Conflicts

If you encounter conflicts when pulling from the wiki:

  1. Resolve conflicts in the docs/ folder
  2. Commit the resolution: 
    git add docs/
git commit -m "docs: resolve wiki merge conflicts"
  3. Push resolved changes: 
    git subtree push --prefix=docs wiki master

📋 Documentation Best Practices

File Naming Convention

  • Use kebab-case: Getting-Started.md, API-Guide.md
  • Be descriptive but concise
  • Avoid spaces and special characters

Content Guidelines

  1. Start with a clear title and overview
  2. Use consistent heading hierarchy (H1 → H2 → H3)
  3. Include code examples where relevant
  4. Add links to related documentation
  5. Keep content up-to-date with code changes

Markdown Tips

  • Use backticks for inline code
  • Use triple backticks with language for code blocks
  • Use **bold** for emphasis
  • Use > blockquotes for important notes
  • Create tables for structured data

🛠️ Troubleshooting

Common Issues

Issue: fatal: working tree has modifications

# Solution: Commit or stash changes first
git add .
git commit -m "docs: work in progress"
# or
git stash

Issue: Wiki changes not appearing on GitHub

# Solution: Ensure you pushed to the wiki remote
git subtree push --prefix=docs wiki master

Issue: Local docs out of sync

# Solution: Pull latest changes from wiki
git subtree pull --prefix=docs wiki master --squash

Getting Help

  • Check Git status: git status
  • View recent commits: git log --oneline -10
  • Check remotes: git remote -v
  • Ask team members or create an issue

🎯 Recommended Documentation

For new developers, consider creating these essential pages:

  • Getting-Started.md - Setup and installation guide
  • Development-Guide.md - Development workflow and tools
  • API-Documentation.md - Backend API reference
  • Testing-Guide.md - How to run and write tests
  • Deployment.md - Build and deployment procedures
  • Contributing.md - Contribution guidelines
  • Troubleshooting.md - Common issues and solutions

Clone this wiki locally