Updating the Contributing file

[jamieliu1023]

Why updating the Contributing file?

The Nebula core team always welcome contributions from the community to make Nebula Graph a better product. During the past two years, there are more than a hundred people submitting code contributions to the core codebase as well as the surrounding tools. Along the journey, we have found that contributing is a process of collaboration, which requires clear communication to make the process more efficient and a more pleasant journey. With that being said, I want to propose changes to the current contributing file to:

1. Make it clear about what is needed and wanted for Nebula Graph from the community
2. Clarify the lifecycle of a pull request so that contributors have proper expectations of what's going on
3. Add some recommended practices of contributing to the Nebula core codebase

What will the new Contributing file contain?

A brief introduction to the Nebula core repo and a reference to some related repos such as clients, plugins, ecosystem tools, etc.

For this section, we need to make it clear that what we are planning to do for the product, how the core is interacting with the clients, plugins, and other ecosystem tools, etc. Not only should we know the designs and rules, but also we need to document them so that the community is well aware of what is expected.

The purpose of this guide

This guide is to provide some recommended practices for contributing code to the Nebula core project. It covers what the Nebula core team is looking for to set some expectations and avoid wasting people's time.
It is required to submit an issue to report a bug, propose an enhancement to the Nebula core, or provide any product feedback.
For this section, we need to take another look at our current issue template and see if they work just fine.

Elaborate on the types of contributions

There can be several types of contributions to the Nebula core: bug fixing and change proposal.

• For bug fixing, we suggest that community members pick an existing bug to work on. For new contributors, we suggest that they choose some good first issues to fix in order to gain some basic understanding on the Nebula core codebase.
  For this section, we need to check: 1) Whether the existing good first are helpful to help people understand the Nebula core codebase; 2) Whether bugs are properly labelled.
• For change proposal, we suggest everyone to first discuss the potential changes in GitHub issues or Discussion before actually implementing. This helps both sides, the contributor and the Nebula core team, be well aware of the design of the changes and the affected scope which is very useful for later code review and merge, large changes in particular. In addition, large changes may have to be split into small changes that tackle just one issue at a time. Also, we should clearly state that for large changes we need to dig deep into what the use-case behind the change is and evaluate possible ways to meet the requirements, which may take time. Also, as to the contributions that are not related to an existing issue, it may take quite some time to provide feedback because the codebase is maintained by a small core team.
  For this section, we need to make sure that: 1) Every pull request comes with an issue explaining or discussing what the PR is trying to solve and how it is designed; 2) Whether there are some special concerns in some areas. For example, what kind of pull requests we are not going to accept and why. There may be some modules that we consider reorg or remove, and we had better clearly state that.

Pull request lifecycle

This part elaborates on the entire lifecycle of a pull request. Also clearly state that sometimes pull requests may go without being merged and there must be a clear explanation why. Also we can make it very clear what kind of pull requests can be merged faster: well-documented, small, passing tests.
For this section, we need to reach consistency about the lifecycle of a pull request in vesoft, as well as what the Nebula core team deems as a good and pleasant pull request.

PR checks

This part tells contributors what checks are performed against the pull request before it can be merged.

The development environment

This section already exists in our current version of Contributing file. Maybe should take another look to make sure if it is clear enough.
Should acceptance testing be included in this section? Do we have acceptance testing?

CC @forest-yuxl @Sophie-Xie

[Sophie-Xie]

That's great!

Just a little suggestion: maybe we should list the workflow to the contributors, then they can know the full view.
And looking forward to the detail updates, we can have more discussions.

[jamieliu1023]

Yes absolutely! If you have no problem with the framework, I'd like to discuss further the details listed in the proposal and then I can provide a draft for everybody's review.