Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
71 lines (48 loc) · 4.22 KB

CONTRIBUTING.md

File metadata and controls

71 lines (48 loc) · 4.22 KB
Raw

Contribution Guidelines

Welcome to the ph-regions repository! We're excited to have you contribute to creating a well-structured, scalable, and fully documented REST API that delivers test/mock data for the Philippines' administrative divisions - including regions, provinces, cities, municipalities, and barangays, ideal for testing and development purposes.

To ensure a smooth contribution process for everyone, please follow these guidelines.

Getting Started

  1. Fork the Repository: Start by forking the repository's "dev" branch to your GitHub account. This creates your own copy of the project where you can make changes.

  2. Clone Your Fork: Clone your forked repository to your local machine using Git. This allows you to work on the files locally.

    git clone https://github.com/yourusername/ph-regions.git

  3. Set Upstream Remote: Add the original repository as an upstream remote to your local clone. This helps you to keep your fork up to date.

    git remote add upstream https://github.com/weaponsforge/ph-regions.git

Making Changes

  1. Create a New Branch: Always work on a new branch for your changes. This keeps your contributions organized and separate from the main branch.

    git checkout -b feat/your-new-feature-name

  2. Add Your Content: Make your changes or additions to the project.

    • If you're adding new content, ensure it's placed in the correct directory, follows intuitive file, variables, and TypeScript naming conventions, and passes the "npm run lint" and "npm run transpile:noemit" scripts. Furthermore, ensure proper middleware validation and API documentation to continue promoting predictable and documented API input and responses.

    • 🔔 INFO
      Key guidelines are also available in the project's root README file under the Project Folder Structure and Adding New Endpoints sections.

  3. Commit Your Changes: After making your changes, commit them to your branch. Use clear and concise commit messages to describe your updates.

    git add .
git commit -m "Add a brief description of your changes"

  4. Keep Your Fork Updated: Regularly sync your fork's "dev" branch with the upstream repository to keep it up to date. This reduces potential merge conflicts.

    git fetch upstream
git checkout dev
git merge upstream/dev
git push origin dev

Submitting Contributions

  1. Push Your Changes: Push your changes to your fork on GitHub.

    git push origin feat/your-new-feature-name

  2. Create a Pull Request (PR): Go to the original ph-regions repository on GitHub and create a new pull request. Base your PR on your feature branch and target the "dev" branch of the upstream repository.

  3. Describe Your Contribution: Provide a clear and detailed description of your pull request. Include the purpose of your changes and any other relevant information.

  4. Review and Collaboration: Once your PR is submitted, the project maintainers will review your contributions. Be open to feedback and be ready to make additional changes if requested.

Guidelines

  1. Quality: Ensure your contributions are high quality, with no spelling or grammatical errors.

  2. Relevance: Content should be relevant to REST API development and testing using Express and TypeScript.

  3. Working functionality: For pull requests involving new features or major updates, ensure the changes are fully functional and optimized. Aim to keep PRs within ~700 lines of code changes, breaking them into smaller, self-contained parts when possible. PRs exceeding ~1000+ lines may be accepted when justified (e.g., major refactors or foundational features).

  4. Respect: Respect the structure and formatting of the existing project. Follow the standard ESLint rules defined in its server/eslint.config.mjs file.

Thank you for contributing to the ph-regions repository. Your efforts help in making test Philippine location data available for testing RESTful API consumption.