> ## Documentation Index
> Fetch the complete documentation index at: https://dos.dzaleka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing Guide

> Learn how to contribute to Dzaleka Online Services and help build a platform for the community

## Welcome Contributors!

Thank you for your interest in contributing to Dzaleka Online Services! This platform serves Dzaleka Refugee Camp by providing information about services, events, news, and resources. Every contribution helps strengthen our community.

<Note>
  Dzaleka Online Services is built with Astro, Tailwind CSS, and deployed on Netlify. We welcome contributions from developers of all skill levels.
</Note>

## Ways to Contribute

There are many ways to contribute to this project:

<CardGroup cols={2}>
  <Card title="Code Contributions" icon="code">
    Fix bugs, add features, or improve performance
  </Card>

  <Card title="Documentation" icon="book">
    Improve guides, fix typos, or add examples
  </Card>

  <Card title="Content" icon="newspaper">
    Add or update service listings, events, or resources
  </Card>

  <Card title="Design" icon="palette">
    Enhance UI/UX or create visual assets
  </Card>
</CardGroup>

## Development Setup

### Prerequisites

Before you begin, ensure you have the following installed:

* **Node.js** (v18 or higher)
* **npm** or **yarn**
* **Git**
* A code editor (VS Code recommended)

### Getting Started

<Steps>
  <Step title="Fork and Clone">
    Fork the repository on GitHub and clone it locally:

    ```bash theme={null}
    git clone https://github.com/YOUR_USERNAME/dos.git
    cd dos
    ```
  </Step>

  <Step title="Install Dependencies">
    Install all required packages:

    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Start Development Server">
    Launch the local development server:

    ```bash theme={null}
    npm run dev
    ```

    The site will be available at `http://localhost:4321`
  </Step>

  <Step title="Make Your Changes">
    Create a new branch for your work:

    ```bash theme={null}
    git checkout -b feature/your-feature-name
    ```
  </Step>
</Steps>

## Project Structure

Understanding the codebase structure will help you navigate and contribute effectively:

```plaintext theme={null}
dos/
├── src/
│   ├── components/     # Reusable UI components
│   ├── content/        # Content collections (services, events, etc.)
│   ├── layouts/        # Page layouts
│   ├── pages/          # Route pages
│   ├── styles/         # Global styles
│   └── utils/          # Utility functions
├── public/             # Static assets
├── astro.config.mjs    # Astro configuration
└── tailwind.config.cjs # Tailwind CSS configuration
```

### Content Collections

The platform uses Astro's content collections for managing structured data:

* `services/` - Community services and organizations
* `events/` - Community events and activities
* `news/` - News articles and updates
* `stories/` - Community stories and testimonials
* `resources/` - Educational and support resources
* `jobs/` - Job opportunities
* `marketplace/` - Marketplace listings

## Code Style Guidelines

### TypeScript

We use TypeScript with strict type checking enabled:

```typescript theme={null}
// Good: Properly typed function
interface Service {
  id: string;
  name: string;
  description: string;
}

function getService(id: string): Service | null {
  // Implementation
  return null;
}

// Bad: Using 'any' type
function getService(id: any): any {
  // Avoid this
}
```

<Warning>
  Always enable strict type checking. Do not use `any` unless absolutely necessary.
</Warning>

### Component Guidelines

**Astro Components:**

```astro theme={null}
---
// Component logic
interface Props {
  title: string;
  description?: string;
}

const { title, description } = Astro.props;
---

<div class="card">
  <h2>{title}</h2>
  {description && <p>{description}</p>}
</div>
```

**React Components:**

```tsx theme={null}
import React from 'react';

interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

export const Button: React.FC<ButtonProps> = ({ 
  label, 
  onClick, 
  variant = 'primary' 
}) => {
  return (
    <button 
      onClick={onClick}
      className={`btn btn-${variant}`}
    >
      {label}
    </button>
  );
};
```

### CSS and Styling

We use Tailwind CSS for styling. Follow these conventions:

```html theme={null}
<!-- Good: Organized class names -->
<div class="flex items-center justify-between p-4 bg-white rounded-lg shadow-sm">
  <h3 class="text-xl font-bold text-gray-900">Title</h3>
</div>

<!-- Good: Using custom CSS when needed -->
<div class="pattern-mudcloth opacity-[0.03]">
  <!-- Content -->
</div>
```

<Tip>
  Group related Tailwind classes together: layout → spacing → colors → typography → effects
</Tip>

### File Naming Conventions

* **Components**: `PascalCase.astro` or `PascalCase.tsx`
* **Pages**: `kebab-case.astro`
* **Utilities**: `camelCase.ts`
* **Content**: `kebab-case.md` or `kebab-case.mdx`

## Pull Request Process

<Steps>
  <Step title="Ensure Quality">
    Before submitting, verify:

    * Code builds without errors: `npm run build`
    * TypeScript types are correct
    * No console errors or warnings
    * Responsive design works on mobile and desktop
  </Step>

  <Step title="Commit Your Changes">
    Write clear, descriptive commit messages:

    ```bash theme={null}
    git add .
    git commit -m "feat: add search functionality to services page"
    ```

    **Commit message format:**

    * `feat:` New feature
    * `fix:` Bug fix
    * `docs:` Documentation changes
    * `style:` Code style changes (formatting)
    * `refactor:` Code refactoring
    * `perf:` Performance improvements
    * `test:` Adding tests
  </Step>

  <Step title="Push to GitHub">
    Push your branch to your fork:

    ```bash theme={null}
    git push origin feature/your-feature-name
    ```
  </Step>

  <Step title="Create Pull Request">
    1. Go to the [original repository](https://github.com/Dzaleka-Connect/dos)
    2. Click "New Pull Request"
    3. Select your branch
    4. Fill out the PR template with:
       * Clear description of changes
       * Related issue numbers
       * Screenshots (if UI changes)
       * Testing steps
  </Step>

  <Step title="Code Review">
    * Respond to feedback promptly
    * Make requested changes
    * Push updates to the same branch
    * Be open to suggestions
  </Step>
</Steps>

## Testing Requirements

### Manual Testing

Before submitting a PR, manually test:

<Accordion title="Testing Checklist">
  * [ ] Build completes without errors
  * [ ] Pages load correctly
  * [ ] Links work as expected
  * [ ] Forms submit properly
  * [ ] Images load and display correctly
  * [ ] Responsive design works (mobile, tablet, desktop)
  * [ ] Browser compatibility (Chrome, Firefox, Safari)
  * [ ] Accessibility (keyboard navigation, screen readers)
</Accordion>

### Build Testing

```bash theme={null}
# Test development build
npm run dev

# Test production build
npm run build
npm run preview
```

## Content Contributions

Adding or updating content is a valuable contribution!

### Adding a New Service

<Steps>
  <Step title="Create Content File">
    Create a new file in `src/content/services/`:

    ```markdown theme={null}
    ---
    name: "Your Service Name"
    category: "Education"
    description: "Brief description of the service"
    location: "Dzaleka Refugee Camp"
    contact:
      email: "contact@example.com"
      phone: "+265 XXX XXX XXX"
    ---

    # About [Service Name]

    Detailed information about the service...
    ```
  </Step>

  <Step title="Add Images">
    Place images in `public/images/services/`:

    ```plaintext theme={null}
    public/images/services/your-service-name.jpg
    ```
  </Step>

  <Step title="Test Locally">
    Run the dev server and verify the new service appears correctly.
  </Step>
</Steps>

### Content Guidelines

<Check>Good practices for content contributions:</Check>

* Write clear, concise descriptions
* Use proper grammar and spelling
* Include accurate contact information
* Add high-quality images (optimized for web)
* Respect privacy and get consent for photos
* Verify information before submitting

## Getting Help

Need assistance? We're here to help!

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/Dzaleka-Connect/dos/issues">
    Ask questions or report problems
  </Card>

  <Card title="Email" icon="envelope" href="mailto:dzalekaconnect@gmail.com">
    Contact the team directly
  </Card>
</CardGroup>

## Community Guidelines

All contributors are expected to follow our [Code of Conduct](/community/code-of-conduct). Be respectful, inclusive, and collaborative.

<Info>
  First-time contributor? Look for issues labeled `good first issue` to get started!
</Info>

## Recognition

We value every contribution! Contributors are:

* Listed in our GitHub repository
* Mentioned in release notes for significant contributions
* Part of building something meaningful for the Dzaleka community

***

**Thank you for contributing to Dzaleka Online Services!** Together, we're building a platform that empowers and connects our community.