Contributing guide

​

Ways to contribute

• Write code: Fix bugs, add new features, or improve existing functionality
• Improve documentation: Help others understand the project better
• Report bugs: Let us know when something doesn’t work as expected
• Share ideas: Suggest new features or improvements
• Test the game: Play daily and provide feedback on the experience

​

Development setup

• Node.js 20 or higher
• pnpm installed globally
• MongoDB Atlas connection string (for database access)

​

Project structure

daily-geogame/
├── app/
│   ├── api/                    # API routes
│   │   ├── country/           # Country data endpoint
│   │   ├── daily/             # Daily country selection
│   │   ├── progress/          # Game progress tracking
│   │   └── stats/             # User statistics
│   ├── components/            # React components
│   │   ├── Footer.tsx
│   │   ├── GameHeader.tsx
│   │   ├── GuessInput.tsx
│   │   ├── GuessList.tsx
│   │   ├── HintGrid.tsx
│   │   ├── HowToPlay.tsx
│   │   ├── LastHint.tsx
│   │   ├── Map.tsx
│   │   ├── Modal.tsx
│   │   ├── Privacy.tsx
│   │   └── StatsModal.tsx
│   ├── hooks/                 # Custom React hooks
│   │   └── useDailyGame.ts
│   ├── lib/                   # Utility libraries
│   │   ├── factbook.ts        # CIA World Factbook data
│   │   ├── geoUtils.ts        # Geography utilities
│   │   └── mongodb.ts         # Database connection
│   ├── types.ts               # TypeScript type definitions
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Home page
├── public/                     # Static assets
├── package.json
├── tsconfig.json
└── eslint.config.mjs

​

Key directories

• app/api/: Server-side API routes that handle game logic, data fetching, and statistics
• app/components/: Reusable React components for the UI
• app/hooks/: Custom hooks like useDailyGame for game state management
• app/lib/: Utility functions for geography calculations, data processing, and database access

​

Code style guidelines

​

TypeScript

• Write type-safe code using TypeScript
• Define types in app/types.ts or co-locate them with components
• Avoid using any unless absolutely necessary (disabled in ESLint config)
• Use interfaces for object shapes and types for unions/primitives

​

React and Next.js

• Use React 19 features and modern patterns
• Prefer function components with hooks
• Use Next.js App Router conventions (server components by default)
• Keep components focused and single-purpose
• Use 'use client' directive only when necessary

​

ESLint

pnpm lint

• @typescript-eslint/no-explicit-any: off
• react/no-unescaped-entities: off
• no-var: off

​

File naming

• Components: PascalCase (e.g., GameHeader.tsx)
• Utilities: camelCase (e.g., geoUtils.ts)
• Hooks: camelCase with use prefix (e.g., useDailyGame.ts)
• API routes: lowercase (e.g., route.ts)

​

Pull request process

git clone https://github.com/YOUR_USERNAME/daily-geogame.git
cd daily-geogame

git checkout -b feature/your-feature-name

pnpm dev

pnpm build

pnpm lint

git add .
git commit -m "feat: add terrain hint animation"

git push origin feature/your-feature-name

​

Commit message conventions

type: brief description

Optional longer description explaining why this change was made.

​

Commit types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, spacing)
• refactor: Code refactoring without changing behavior
• perf: Performance improvements
• test: Adding or updating tests
• chore: Maintenance tasks, dependencies

​

Examples

feat: add hint reveal animation
fix: correct neighbor country highlighting on map
docs: update installation instructions
refactor: simplify guess validation logic

​

Issue reporting guidelines

​

Bug reports

1. Clear description: What went wrong?
2. Steps to reproduce: How can we see the bug?
3. Expected behavior: What should have happened?
4. Actual behavior: What actually happened?
5. Environment: Browser, OS, device type
6. Screenshots: If applicable

​

Feature requests

1. The problem: What need does this address?
2. Your solution: How would this feature work?
3. Alternatives: What other approaches did you consider?
4. Examples: Are there similar features elsewhere?

​

Where to report

​

Code of conduct

• Be respectful and considerate
• Welcome newcomers and help them learn
• Focus on constructive feedback
• Assume good intentions
• Respect differing opinions and experiences

​

License

• Your code can be freely used, modified, and distributed
• You retain copyright to your contributions
• The project can continue to be open source