Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
285 lines (188 loc) · 9.76 KB

CONTRIBUTING.md

File metadata and controls

285 lines (188 loc) · 9.76 KB

Contributing to Zoea Open Source

Welcome! 🎉 We're thrilled you're considering contributing to Zoea Open Source. This repository is designed to help beginners get comfortable with GitHub, contributions, and open source collaboration.

This document will walk you through how to get started and how you can contribute. Whether you're fixing typos, writing code, or improving docs, you're making an impact.

📁 Repository Structure

Here’s what you’ll find at the root of this repo:

zoea-opensource/
│
├── guides/      ← Markdown guides to help you learn how to contribute
├── solutions/   ← Contributions from users: code, tutorials, experiments, etc.
├── translations/   ← Guide Translations to help you read in your preferred language.

Ways You Can Contribute

You can contribute in many ways, including:

📝 Guides

Add or improve markdown files in the guides/ folder:

  • How-tos (e.g., “How to Make Your First PR”)
  • Git tutorials
  • Open source contribution tips
  • Anything that can help beginners get started
  • Translations

💡 Solutions

In the solutions/ folder, you can:

  • Submit code snippets, mini projects, or experiments
  • Fix simple bugs or improve existing code
  • Resolve and explain merge conflicts (great learning opportunity!)
  • Add example PRs for learning purposes

You can even submit creative solutions to example challenges we'll post.

🛠 Other Contributions

  • Fix typos or grammar issues in markdown files
  • Improve file organisation
  • Help with formatting and structure of documentation
  • Add helpful links and resources

Getting Started

Note

POV: Please read the following simple steps on how to contribute. This will make life easier and will avoid wasting time on things which are not requested. ✨

Steps to follow

Open a copy of this page on another tab to help you follow up.

Step 1: Star The Repo (Optional)
  • Star the repo by pressing the topmost-right button to start your wonderful journey
Image
Step 2: Fork this repo
Image
Step 3: Clone the forked repo to your machine
  • Method 1: GitHub Desktop

⚠️ NOTE: If you're not familiar with Git, using GitHub Desktop Application is a better start. If you choose this method, make sure to download it before continuing reading.

❗❗ Access link to download here.

  • Method 2: Git

Clone the forked repository. Open git bash and type:

git clone https://github.com/<your-github-username>/zoea-opensource.git
cd zoea-opensource
git config --global user.name "<your GitHub user name>" && git config --global user.email "your GitHub primary email"

This makes a local copy of the repository in your machine.

⚠️ Replace <your-github-username>!

Learn more about forking and cloning a repo.

Step 4: Create a new branch for your changes

Always keep your local copy of the repository updated with the original repository. Before making any changes and/or in an appropriate interval, follow the following steps:

  • Method 1: GitHub Desktop

Learn more about how to create a new branch here and how to fetch and pull origin from/to your local machine here.

Learn more about how to fetch and pull origin from/to your local machine using GitHub Desktop here.

  • Method 2: Git

Run the following commands carefully to update your local repository

# If you cloned a while ago, get the latest changes from upstream
git checkout main
git pull upstream main

# Make a feature branch (Always check your current branch is up to date
# before creating a new branch from it to avoid merge conflicts)
git checkout -b <your-new-branch-name>

#
Step 5: Ready, Set, Go...
  • Once you have completed these steps, you are ready to start contributing to the project and creating pull requests.

Translation Contribution

How to do this* In the Translation Guide readme, the language of translation will be included inside a []bracket, and the link inside a ()

So it should look something like:

[language](link)

Code Snippet Contribution

  • Create a folder if you want to contribute a new code snippet in a different language.
    1. The folder name Must be the name of the language, and the files must be relevant to the code you want to submit.
    2. The folder created Must be added to the path: Solutions/Snippets, followed by the language name directory, then the file
      Example: If the new snippet is in Java programming, the path should be as follows. Solutions/Snippets/Java/your-file-name.java
  • If your language snipped directory already exists, then add your file to the existing directory

Guide Contribution

  • Ensure your guide is meaningful and beginner-friendly
  • Don't forget to add a README.md in your folder.
  • Method 1: GitHub Desktop

Learn more about how to make pull requests from your local machine using GitHub Desktop to the main repo here.

  • Method 2: Git

Add and commit with a clear message using git add, git commit:

git add -A
git commit -m "<your message>"

Push the code to your repository.

git push -u origin <branch-name>

Make sure you have no conflicts. 🙂 🙂

Step 6: Open a Pull Request (PR)

Go to the GitHub page of your fork, and make a pull request:

Read more about pull requests on the GitHub help pages.

  • Now wait, until your Pull Request is approved! If there are any conflicts, you will get a notification.

📌 Guidelines

  • ✅ Be kind and respectful – especially to beginners
  • ✅ Keep content beginner-friendly and easy to understand
  • ✅ Follow markdown best practices for guides/
  • ✅ Organise code clearly for solutions/
  • ✅ Include comments where necessary in code
  • ✅ Keep PRs focused – one topic/change per PR
  • ✅ Feel free to ask for help via Issues or Discussions

Examples

Here are some example guides you can pick to get started with the contribution.

Fixing Merge Conflicts Adding name to Contributors.md

🚧 What We're Still Planning

We're currently working on:

  • Creating beginner-friendly issues for you to tackle
  • Templates for code challenges
  • Directory structure best practices

Have ideas? Open an issue and share it!

Need Help?

No worries, this is a learning space. If you're unsure how to start, visit the guides/ directory or ask a question in the Discussions tab.

Reporting a bug

So you've found a bug, and want to help us fix it? Before filing a bug report, please double-check that the bug hasn't already been reported. You can do so on our issue tracker. If something hasn't been raised, you can go ahead and create a new issue with the following information:

  • On which page did the error happen?
  • How can the error be reproduced?
  • If possible, please also provide an error message or a screenshot to illustrate the problem

If you want to be really thorough, there is a great overview on Stack Overflow of what you should consider when reporting a bug.

It goes without saying that you're welcome to help investigate further and/or find a fix for the bug. If you want to do so, just mention it in your bug report and offer your help!

Thank You

Thank you for being part of Zoea Open Source. Your contribution—big or small is helping someone else grow. That’s the magic of open source.