Skip to content

Latest commit

 

History

History
166 lines (117 loc) · 9.23 KB

CONTRIBUTING.md

File metadata and controls

166 lines (117 loc) · 9.23 KB
Raw

Contributing to elimu.ai 👩🏽‍💻

The mission of elimu.ai is to build innovative learning software that empowers out-of-school children to teach themselves basic reading📖, writing✍🏽, and math🔢 within 6 months.

We believe that having the opportunity to learn these foundational life skills should be the right of every child, not matter her social or geographical background. This is currently not the case for 10% of the human population of primary age (6-11 years old), who are out-of-school.

Since elimu.ai is an open source project, anyone is welcome to contribute towards this goal. We welcome different skills, cultures, perspectives, attitudes, and experiences. Also see our Code of Conduct.

This document explains the step-by-step process and guidelines for contributing to any of the repositories in the elimu.ai GitHub organization.

Each GitHub repository has maintainers responsible for reviewing code submitted by contributors. The appointment of maintainers is based on previous contributions (meritocracy).

Contributor Workflow 🔀

Outside Contributor vs Core Contributor

The first step is to decide what type of contributor you are. In general, every contributor would belong to one of the following:

  1. Outside contributor

    Being an outside contributor means that you have not been added to the elimu.ai GitHub organization. In practice this means that you do not have access to create new repositories or new repository branches.

  2. Member contributor

    Being a member contributor means that you have been added to the elimu.ai GitHub organization. This gives you access to create new repositories and repository branches.

How to Know Which Task to Work On

  1. Each Android app/game has its own GitHub repository. Start by identifying a repository in which you would like to contribute: https://github.com/elimu-ai. And to get an understanding of the overall software architecture, see https://github.com/elimu-ai/wiki/blob/main/SOFTWARE_ARCHITECTURE.md.

    Software Architecture

  2. Look at the code in the repository to see if your skills match those required. If in doubt, post your questions in our Community Chat 👋🏽 or send an e-mail to [email protected].

  3. When you have selected a repository, click the "Issues" tab of the repository. Within each project you will see a collection of issues. Feel free to start working on any issue that has not already been assigned to another contributor.

  4. If you feel lost, take a look at the issues labeled good first issue. These are tasks that are considered as good entry-points for first-time contributors. Here are some examples:

  5. You are also welcome to create new GitHub issues yourself. For example, if you have discovered a bug or want to suggest a new feature, press the "New issue" button.

How to Implement and Submit Your Work

Once you have identified a task to work on, there is a specific workflow that you should follow. This workflow is mostly identical for both outside and member contributors, except from the way to create a new GitHub branch to work on (Step 1):

  1. If you are an outside contributor, fork the repository to your own GitHub account. (If you are a member contributor, you will create a new branch directly in the main repository.)

  2. Create a new branch for the GitHub issue that you will be working on. If, for example the issue you have picked is titled "Upgrade to the latest Gradle version", create a new branch with a title like build(gradle): upgrade gradle.

  3. Remember to include a reference to the GitHub issue number in each commit to make it easier for future contributors to understand each code change. E.g. closes #57.

  4. Keep each commit small so that diffs are easy to read and understand for people looking at your code in the future. A pull request should always be focused to doing one thing, for example fixing a bug or adding a new feature, but not a mixture. Avoid large commits and pull requests which attempt to do too much at once, as this makes code review difficult.

  5. If you want to add things like formatting fixes or refactoring, etc, do not mix those with the actual code change related to an issue. To make the actual code change easier to read, separate refactoring into a new branch (and a new issue).

  6. Once you are ready to receive feedback on your branch, create a pull request for merging it into the main branch. Include a reference to the GitHub issue in the pull request's description, e.g. closes #57, so that the issue gets closed automatically when the pull request merges.

  7. Every pull request requires at least one approved peer review before being merged, so add at least one person as a code reviewer of your pull request. To find out who to add, click "Insights" → "Contributors" too see an overview of the most active contributors for each repository. If you are unsure who to add, use these: nya-elimu, jo-elimu and gscdev.

  8. Once your pull request has been reviewed and approved, it can be merged. The person who created the branch (you) will be the person responsible for merging the branch. So your peers reviewing your code will not merge the branch; that is your responsibility.

Workflow Example: webapp

Introduction

As an outside collaborator, you are free to fork the repository and create pull requests from your fork.

However, as a member contributor who has been added to the GitHub organization, the work flow looks like this:

Work Flow

  1. Select a GitHub issue to work on. Either select an existing issue from https://github.com/elimu-ai/webapp/issues or create a new one, and assign yourself to the issue.

  2. Create a new branch for the GitHub issue:

    .

  3. Switch to the branch you created and implement your code changes on that branch.

  4. Once ready for testing, create a pull request for your branch for merging it into the main branch. Your pull request needs at least one approved review in order to be merged. When assigning reviewers, add one or more of the project's maintainers:

    If the maintainers are too slow to get back to you, reach out to the open source community via chat or e-mail.

  5. Once your pull request has been approved by at least one project maintainer, press the "merge" button. This will merge your code changes into the main branch and deploy them to the test servers at https://<language>.test.elimu.ai.

  6. If all of the regression tests pass, ask a maintainer to deploy the changes to the production servers at https://<language>.elimu.ai.

Get to know some of our past and current open-source contributors and maintainers in CONTRIBUTORS.md.

If any of the above steps are unclear, or you have any other questions or comments, please reach out to the community via chat or e-mail. Thank you for contributing 🙌🏽

elimu.ai - Free open-source learning software for out-of-school children ✨🚀

Website 🌐  •  Wiki 📃  •  Projects 👩🏽‍💻  •  Milestones 🎯  •  Community 👋🏽  •  Support 💜