Skip to content

project-specific contribution guidelines #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
snowvirus wants to merge 1 commit into
base: main
Choose a base branch
from
Open

project-specific contribution guidelines #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
320 changes: 43 additions & 277 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,305 +1,71 @@
# Contributing to OpenCare-Africa
# Contributing to OpenCare-Core

Thank you for your interest in contributing to OpenCare-Africa! We welcome contributions from developers, healthcare professionals, and anyone passionate about improving healthcare systems in Africa.
Thank you for your interest in contributing to OpenCare-Core! We are excited to have you join our community and help improve healthcare systems in Africa.

## Table of Contents
## 🚀 Getting Started

- [Code of Conduct](#code-of-conduct)
- [How Can I Contribute?](#how-can-i-contribute)
- [Getting Started](#getting-started)
- [Development Workflow](#development-workflow)
- [Code Standards](#code-standards)
- [Testing](#testing)
- [Documentation](#documentation)
- [Security](#security)
- [Questions or Need Help?](#questions-or-need-help)
To contribute to this project, please follow these steps:

## Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [conduct@opencare-africa.org](mailto:conduct@opencare-africa.org).

## How Can I Contribute?

### Reporting Bugs

- Use the GitHub issue tracker
- Include detailed steps to reproduce the bug
- Provide environment information (OS, Python version, Django version)
- Include error logs and screenshots if applicable

### Suggesting Enhancements

- Use the GitHub issue tracker with the "enhancement" label
- Describe the problem and proposed solution
- Consider the impact on existing functionality
- Think about backward compatibility

### Code Contributions

- Bug fixes
- New features
- Performance improvements
- Documentation updates
- Test coverage improvements

## Getting Started

### Prerequisites

- Python 3.8+
- Git
- PostgreSQL (for production-like development)
- Redis (for caching and Celery)

### Setup Development Environment

1. **Fork and Clone the Repository**
```bash
git clone https://github.com/your-username/OpenCare-Africa.git
cd OpenCare-Africa
```

2. **Create Virtual Environment**
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```

3. **Install Dependencies**
```bash
pip install -r requirements-dev.txt
```

4. **Environment Configuration**
```bash
cp .env.example .env
# Edit .env with your local settings
```

5. **Database Setup**
```bash
python manage.py migrate
python manage.py createsuperuser
```

6. **Run Development Server**
```bash
python manage.py runserver
```

## Development Workflow

### 1. Create a Feature Branch
### 1. Fork and Clone
Fork the repository on GitHub and clone your fork locally:

```bash
git checkout -b feature/amazing-feature
# or
git checkout -b fix/bug-description
git clone https://github.com/your-username/OpenCare-Core.git
cd OpenCare-Core
```

### 2. Make Your Changes

- Write clean, readable code
- Follow the coding standards below
- Add tests for new functionality
- Update documentation as needed

### 3. Commit Your Changes

Use conventional commit format:

```bash
git commit -m "feat: add patient search functionality"
git commit -m "fix: resolve authentication issue in API"
git commit -m "docs: update API documentation"
git commit -m "test: add unit tests for patient model"
```

**Commit Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks

### 4. Push and Create Pull Request

```bash
git push origin feature/amazing-feature
```

Then create a Pull Request on GitHub with:
- Clear description of changes
- Link to related issues
- Screenshots for UI changes
- Test results

## Code Standards

### Python/Django Standards

- Follow PEP 8 style guide
- Use meaningful variable and function names
- Write docstrings for all functions and classes
- Keep functions small and focused
- Use type hints where appropriate

### Django Best Practices

- Use Django ORM efficiently
- Implement proper model relationships
- Use Django forms and serializers
- Follow Django security best practices
- Implement proper error handling

### Code Quality Tools

We use several tools to maintain code quality:

Add the original repository as a remote named `upstream`:
```bash
# Format code with Black
black .

# Sort imports with isort
isort .

# Check code style with flake8
flake8 .

# Run security checks with bandit
bandit -r .

# Run tests with coverage
coverage run --source='.' manage.py test
coverage report
git remote add upstream https://github.com/bos-com/OpenCare-Core.git
```

## Testing
### 2. Branching Strategy
Always create a new branch for your work. We use the following naming convention:

### Running Tests
- `feature/your-feature-name` for new features
- `fix/your-fix-name` for bug fixes
- `docs/your-topic` for documentation updates

```bash
# Run all tests
python manage.py test

# Run specific app tests
python manage.py test apps.patients

# Run with coverage
coverage run --source='.' manage.py test
coverage report
coverage html # Generate HTML report
```

### Writing Tests

- Write tests for all new functionality
- Aim for at least 80% code coverage
- Use descriptive test names
- Test both success and failure cases
- Use factories for test data (factory-boy)

### Test Structure

```python
class PatientModelTest(TestCase):
def setUp(self):
"""Set up test data."""
self.patient = PatientFactory()

def test_patient_creation(self):
"""Test that patient can be created."""
self.assertIsNotNone(self.patient)
self.assertEqual(self.patient.first_name, "John")

def test_patient_full_name(self):
"""Test patient full name method."""
expected = f"{self.patient.first_name} {self.patient.last_name}"
self.assertEqual(self.patient.get_full_name(), expected)
git checkout -b feature/amazing-new-feature
```

## Documentation
### 3. Commit Message Style
We follow the **Conventional Commits** specification. This helps us generate automated changelogs.

### Code Documentation
Format: `<type>(<scope>): <description>`

- Write clear docstrings for all functions and classes
- Use Google or NumPy docstring format
- Include examples for complex functions
- Document parameters, return values, and exceptions
**Types:**
- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation only changes
- `style`: Changes that do not affect the meaning of the code (white-space, formatting, etc)
- `refactor`: A code change that neither fixes a bug nor adds a feature
- `test`: Adding missing tests or correcting existing tests
- `chore`: Changes to the build process or auxiliary tools and libraries

### API Documentation
**Example:** `feat(patients): add ability to search patients by ID`

- Update API documentation when endpoints change
- Include request/response examples
- Document authentication requirements
- Provide clear error messages
### 4. Pull Request (PR) Process
When you are ready to submit your changes:

### User Documentation
1. **Push** your branch to your fork:
```bash
git push origin feature/amazing-new-feature
```
2. **Open a PR** on GitHub.
3. **Description**: In the PR description, explain what you changed and why.
4. **Link Issues**: If your PR fixes an open issue, link it using keywords like `Closes #123`.
5. **Review**: A maintainer will review your code. Address any feedback by pushing additional commits to your branch.

- Update README.md for major changes
- Maintain setup and deployment guides
- Document configuration options
- Provide troubleshooting guides

## Security

### Security Guidelines

- Never commit sensitive information (API keys, passwords)
- Use environment variables for configuration
- Implement proper authentication and authorization
- Validate all user inputs
- Use HTTPS in production
- Follow OWASP security guidelines

### Reporting Security Issues

If you discover a security vulnerability, please:

1. **DO NOT** create a public GitHub issue
2. Email security@opencare-africa.org
3. Include detailed information about the vulnerability
4. Allow time for the security team to respond

## Questions or Need Help?

### Getting Help

- Check existing documentation
- Search existing issues and discussions
- Join our community discussions
- Contact the development team

### Communication Channels

- **GitHub Issues**: For bugs and feature requests
- **GitHub Discussions**: For questions and general discussion
- **Email**: support@opencare-africa.org
- **Community Forum**: [forum.opencare-africa.org](https://forum.opencare-africa.org)

### Mentorship

New contributors are welcome! We offer:

- Code review and feedback
- Pair programming sessions
- Mentorship from experienced contributors
- Regular office hours for questions

## Recognition

Contributors will be recognized in:
---

- Project README
- Release notes
- Contributor hall of fame
- Annual contributor acknowledgments
## 🛠️ Development Setup

## Thank You!
For detailed instructions on setting up your local environment, please refer to the [README.md](README.md#🚀-quick-start).

Your contributions help make healthcare better for millions of people across Africa. Every line of code, bug report, or documentation improvement makes a difference.
## ⚖️ Code of Conduct
By participating in this project, you agree to abide by our Code of Conduct.

---

Expand Down
11 changes: 5 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -394,12 +394,11 @@ docker run -e DJANGO_SETTINGS_MODULE=config.settings.production opencare-africa:

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
We welcome contributions from the community! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions on:
- How to fork and clone the repository.
- Our branching strategy.
- Our commit message style.
- How to submit a Pull Request.

### Development Guidelines
- Follow PEP 8 style guidelines
Expand Down