How to contribute

Contributing to Zavi Family Monorepo.

In this project, we heavily utilise GitHub features to document and signal any progress in the development process.

Understanding GitHub Projects

In 2021, GitHub launched a new Project planning feature in beta. You can read GitHub's official document about this new feature.

We are trying to utilise this new feature to manage our issues better. Here is the way we are using it in this project.

Backlog

To find the state of all issues, please visit the Zavi Family Monorepo board. These are what each column on the board means:

Epics list

To visualise the list of epics covering all issues in this project and understand the overall state of this project, please visit the Epics list tab.

Finding or creating issues

Most contributions start from defining issues. Anyone can open an issue for discussion. You can head to this link for a deep understanding of the Issues. Specifically, you can start finding several Issues in our Issues tab. There are only two categories in the Issues section, Open and Closed.

Open Issues

Open Issues are issues that need more attention, and we need to work on them. Contributors should pick any of the Open Issues and start working on them.

Closed Issues

Closed Issues are issues that have been completed or don't need further action. We can reopen Closed issues if contributors find any issues related to them sometime in the future.

Please pay attention to every issue attribute. Other contributors might reference every issue through Linked Pull Requests. If an issue has a linked pull request, someone is currently handling it. We encourage contributors to submit a draft pull request to avoid redundant work when working on an issue.

For beginners: good first issue label

As mentioned here, GitHub treats the good first issue label in a particular way to help beginners contribute to an open-source project. The good first issue label informed us about the difficulty level of an issue. It means that an issue with a good first issue label suits perfectly for contributors who would like to contribute to an open-source project.

How to find issues with good first issue label:

1. The easiest way is to go into the github.com/<owner>/<repository>/contribute link. In this case, you can go to this link. That link will list all the issues with the good first issue label.
2. Another way is to head to the Issues repository section and click the Labels section beside Milestones. There you can see a lot of labels for the issues in the repository. Then find and click the good first issue label.

Working on issues

Getting ready

Before working on an issue, please make sure to:

1. Fork the repo properly. Even if you have done it before, we still advise you to read/skim the official guide.
2. Clone your forked repository and set it up by following the Getting Started guide.
3. Check any open pull requests so that no one is working on the issue.
4. Create a new branch from the main branch. It is essential to allow the maintainers to update the code changes directly when they have suggestions.

Issue assignment & communication

Once you're ready with your branch and have something to contribute, you'll want to let everyone know you are working on the issue. To communicate this, we are using GitHub's Draft Pull Requests.

Draft Pull Request is like a regular Pull Request, but we can't merge it until we mark it as "ready for review". It signals other contributors that it's a work in progress. It is necessary to signal other contributors that the work for the particular issue has started and is still in progress. Also, it is a better approach to use as a communication tool between contributors because we can provide additional information other than viewing the changed files.

Creating a Draft Pull Request

Steps to creating a Draft Pull Request:

1. Commit and push your new changes into the remote repository. Please refer to @commitlint/config-conventional for your commit message, or you can use commitlint.io to assist you in composing the commit message.
2. Head to the Pull requests section on your forked repository, and hit New pull request.

   

3. Select your forked repository for the head repository, and compare with the branch in which you are changing.

   

4. Put a clear title and description in your pull request. Make sure the description follows our guide below.

   

5. Choose `Create draft pull request`` (like in the image above) and hit the green button.
6. Don't forget to mark your Draft Pull Request as Ready for review after you commit all the changes.

Formatting Pull Request description

To properly link a pull request to an issue, there is one tiny requirement text to put in a Pull Request description. Please make sure to mention the issue that you're working on correctly. Replace this text <!-- mention the issue that you're trying to close with this PR --> from the template with the issue number. Example:

Closes #318

## Description

Update **`Start working on Issues`** section with clearer instructions on
getting ready to work on an issue.

Marking Pull Request as Ready for Review

When you have finished working on the issue, you can mark your Draft Pull Request as Ready for review. This action will notify other contributors that the issue is ready for review. Please follow these steps to do so.

Disabling GitHub Actions

We recommend contributors turn off GitHub action on your forked repository.

1. Go to Setting on your forked repository
2. Choose Action on the sidebar
3. Disable Actions