Skip to content

Latest commit

 

History

History
182 lines (129 loc) · 9.39 KB

CONTRIBUTING.md

File metadata and controls

182 lines (129 loc) · 9.39 KB
Raw

Contributing Guidelines

First, thank you for considering contributions to Zadig!

We welcome all sorts of contributions: from fixing a typo, updating a documentation, raising a bug, proposing a feature request, to proposing a design and driving all the implementations in end-to-end manner.

TOC

Prerequisite

For every commit, be sure to sign off on the DCO.

Zadig's success heavily relies on a healthy community, and it's up to every one of us to maintain it. This is a reminder that all contributions are expected to adhere to our Code of Conduct.

Setup

You should first fork the specific repository you want to contribute to. Please follow the instructions here to set Zadig up for running.

Before submitting any new issues or proposing any new changes, please check the open issues to make sure the efforts aren't duplicated. There are a few labels that could help you navigate through the issues:

  • If you are looking for some startup issues to get your hands on, you could follow the #good-first-issue issues.

  • If you are looking for some more serious challenges, you could check out our #help-wanted issues.

  • Or some random bugfix, check out #bugs.

Contribution option 1 - reporting an issue

For security related issues, please drop an email to [email protected] instead. For non-security related issues, please read on.

There are 5 types of labels for issues that you need to think of:

  1. documentation
  2. bug
  3. feature request
  4. question
  5. enhancement

If you understand which services are involved with the new issue, please also attach the relevant label(s) to it. You could search for service/ prefix to find the correct label. If you aren't sure about this, feel free to leave it open, our maintainers will get to it.

If you have checked that no duplicated issues existed and decided to create a new issue, choose the label accordingly and follow the issue template. Please be as specific as possible assuming low or no context from whoever reading the issue.

How issues will be handled

All issues created will be triaged by our maintainers:

  1. The maintainers will double check the issues were created with the proper label, update them otherwise.
  2. They'll make decisions whether the issues will be accepted, see next point.
  3. Certain tags might be applied by our maintainers accordingly, there are mainly 4 of them:
    1. duplicate
    2. wonfix: rationales will be provided, e.g. work as intended, obsolete, infeasible, out of scope
    3. good first issue: good candidates suitable for onboarding.
    4. good intermediate issue: a more serious challenge that is up for grabs to the community.
  4. The issues are open for grab now.
  5. Periodically, the maintainers will double check that all issues are up-to-date, stale ones will be removed.

Contribution option 2 - update a doc

For trivial doc changes

For trivial doc changes, such as fixing a typo, updating a link, go ahead and create a pull request. One of our maintainers will get to it. Please follow our PR and commit guidelines below.

For non-trivial doc changes

If you are looking for a more serious documentation changes, such as refactoring a full page, please follow the instructions of non-trivial code changes below. You'll need an issue to track this and a design outlining your proposal and have the design approved first.

Contribution option 3 - code changes

For any code changes, you need to have an associated issue: either an existing one or create a new one.

to prevent duplication, please claim an issue by commenting on it that you are working on the issue.

For trivial changes

  1. You could describe your design ideas in the issue; but if you are confident enough with your change, feel free to skip this step too.
  2. Work on the changes in your forked repository.
  3. Please follow our PR and commit guidelines, one of our maintainers will review your PR.
  4. If you have changed the backend APIs in aslan microservice, you need to update our API doc accordingly.

For non-trivial changes

  1. You need to write a design to describe what you are trying to address and how by making a copy of Zadig design template and filling in the template.
  2. Add the design in markdown format in community/rfc folder, name it as yyyy-MM-dd-my-design-name.md. Please send a separate PR for this. One of our maintainers will get to it.
  3. Once the design is approved and PR merged, you can start working on the issue following the solutions outlined in the design.
  4. We highly encourage atomic PRs, so if your change can be broken down into several smaller sub-tasks, please do it and create one PR for each.
  5. For each sub-task, follow the trivial-changes guidelines above.

Update API doc

If you only modified APIs from services other than aslan, you could ignore this since we don't have API docs for them yet. For aslan service, we use Swag to automatically generate API docs hosted by Swagger based on the swag declarative API comments.

So if you have added or modified any API on aslan service, please:

  1. Document your API Handler following swag declarative API comments.

  2. Update the swagger API doc with the following command:

cd [your root path of Zadig-X]

swag init -d ./lib/microservice/aslan/ -g server/rest/router.go -o ./lib/microservice/aslan/server/rest/doc

Check out Swag CLI for more details.

Note: If your generated doc/docs.go contains "github.com/alecthomas/template" (used by early swag versions), please change it to "text/template".

  1. Double check the generated API doc works as expected in your testing environment under path /api/aslan/apidocs/index.html.

Contributor resources

PR and commit guidelines

  • Please follow our PR template and write clear descriptions as much as possible.
  • Please keep each commit atomic and write crisp, clear and accurate commit messages.
  • Don't forget signing off the DCO for each commit.
  • We recommend you to create PR early once you decide to work on something. However, it must be prefaced with "WIP: [title]" until it's ready for review. Once it is ready for review, remove the prefix "WIP: ", one of our maintainers will get to it.
  • Make sure your changes passed all the tests.
  • Please rely on the official Go Code Review Comments as the code style guideline.
  • Attach the relevant label(s) to your PR by following the same guideline for issues in Contribution option 1 - reporting an issue
  • To test your changes, please follow how to debug your code

Growth path for contributors

We have established a well-lit path for contributor's progression. Please check out GOVERNANCE for more information.

Where can you get support

More resources