Skip to main content

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.
Dzaleka Online Services is built with Astro, Tailwind CSS, and deployed on Netlify. We welcome contributions from developers of all skill levels.

Ways to Contribute

There are many ways to contribute to this project:

Code Contributions

Fix bugs, add features, or improve performance

Documentation

Improve guides, fix typos, or add examples

Content

Add or update service listings, events, or resources

Design

Enhance UI/UX or create visual assets

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

1

Fork and Clone

Fork the repository on GitHub and clone it locally:
git clone https://github.com/YOUR_USERNAME/dos.git
cd dos
2

Install Dependencies

Install all required packages:
npm install
3

Start Development Server

Launch the local development server:
npm run dev
The site will be available at http://localhost:4321
4

Make Your Changes

Create a new branch for your work:
git checkout -b feature/your-feature-name

Project Structure

Understanding the codebase structure will help you navigate and contribute effectively:
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:
// 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
}
Always enable strict type checking. Do not use any unless absolutely necessary.

Component Guidelines

Astro Components:
---
// 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:
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:
<!-- 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>
Group related Tailwind classes together: layout → spacing → colors → typography → effects

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

1

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
2

Commit Your Changes

Write clear, descriptive commit messages:
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
3

Push to GitHub

Push your branch to your fork:
git push origin feature/your-feature-name
4

Create Pull Request

  1. Go to the original repository
  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
5

Code Review

  • Respond to feedback promptly
  • Make requested changes
  • Push updates to the same branch
  • Be open to suggestions

Testing Requirements

Manual Testing

Before submitting a PR, manually test:
  • 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)

Build Testing

# 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

1

Create Content File

Create a new file in src/content/services/:
---
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...
2

Add Images

Place images in public/images/services/:
public/images/services/your-service-name.jpg
3

Test Locally

Run the dev server and verify the new service appears correctly.

Content Guidelines

Good practices for content contributions:
  • 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!

Community Guidelines

All contributors are expected to follow our Code of Conduct. Be respectful, inclusive, and collaborative.
First-time contributor? Look for issues labeled good first issue to get started!

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.