Contributing Guide - Dzaleka Online Services

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

Fork and Clone

Fork the repository on GitHub and clone it locally:

git clone https://github.com/YOUR_USERNAME/dos.git
cd dos

Install Dependencies

Install all required packages:

npm install

Start Development Server

Launch the local development server:

npm run dev

The site will be available at http://localhost:4321

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

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

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

Push to GitHub

Push your branch to your fork:

git push origin feature/your-feature-name

Create Pull Request

Go to the original repository
Click “New Pull Request”
Select your branch
Fill out the PR template with:
- Clear description of changes
- Related issue numbers
- Screenshots (if UI changes)
- Testing steps

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:

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)

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

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...

Add Images

Place images in public/images/services/:

public/images/services/your-service-name.jpg

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!

GitHub Issues

Ask questions or report problems

Email

Contact the team directly

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.

​Welcome Contributors!

​Ways to Contribute

Code Contributions

Documentation

Content

Design

​Development Setup

​Prerequisites

​Getting Started

​Project Structure

​Content Collections

​Code Style Guidelines

​TypeScript

​Component Guidelines

​CSS and Styling

​File Naming Conventions

​Pull Request Process

​Testing Requirements

​Manual Testing

​Build Testing

​Content Contributions

​Adding a New Service

​Content Guidelines

​Getting Help

GitHub Issues

Email

​Community Guidelines

​Recognition

Welcome Contributors!

Ways to Contribute

Development Setup

Prerequisites

Getting Started

Project Structure

Content Collections

Code Style Guidelines

TypeScript

Component Guidelines

CSS and Styling

File Naming Conventions

Pull Request Process

Testing Requirements

Manual Testing

Build Testing

Content Contributions

Adding a New Service

Content Guidelines

Getting Help

Community Guidelines

Recognition