We’d love for any contribution you can make to Taiko. Welcome to the contributing manual!
Table of contents:
Make a contribution
Thank you for exploring the opportunity to contribute to Taiko.xyz. Whether you’re an experienced developer or just starting, we value and welcome your unique contributions.
Here are some ways you can contribute:
- Open a new issue here (please check the issue does not already exist).
- Work on an existing issue (check out the good first issues list on our public project board).
Once the pull request is merged to one of Taiko’s GitHub repositories (you can see which repositories here: 2023 Taiko Contributor GitPOAP), you will be automatically awarded a Taiko Contributor GitPOAP. Opening a good new issue (not a spam issue) is also eligible for a GitPOAP, just leave a comment and we will manually invoke a GitHub bot that will send the GitPOAP.
You can learn how to best contribute to Taiko by watching the “Taiko Contributing Guide - Community Workshop” video on our YouTube channel.
This section describes our coding standards at Taiko.
Basic requirements for PRs
Before we can consider your contributions, please have a look at the following requirements:
- Any contribution must follow the standards documented in this file.
- The scope must be larger than a simple rename, or typo fix. We kindly request that small, incremental updates be combined into more substantial pull requests. This approach will streamline our development and ensure focus on core improvements.
Specify the scope of your change with a conventional commit in the PR title (for example,
feat(scope): description of feature). This will be squashed and merged into the
main branch. You can find the full list of allowed scopes here.
Because we squash all of the changes into a single commit, please try to keep the PR limited to the scope specified in the commit message. This commit message will end up in the automated changelog by checking which packages are affected by the commit.
feat(scope): description of feature should only impact the
scope package. If your change is a global one, you can use
feat: description of feature, for example.
Note: The taiko team will evaluate all PRs and may close any pull requests that do not follow the standards outlined in this document. Please note, small pull requests will not be considered for future airdrops. We encourage contributions that make significant enhancements to the project.
Source code comments
Follow the NatSpec format for documenting smart contract source code. Please adhere to a few additional standards:
/** */ for multi-line NatSpec comments for consistency. All NatSpec comments should use
/// instead of
/** */. Additional explanatory comments should use
//, even for multi-line comments.
Omit the usage of
@notice and let the compiler automatically pick it up to save column space. For example, this:
For multi-line annotations, do not “align”. For example, this is wrong:
This is correct:
Extra line breaks
Use extra line breaks as you see fit. By default, do not use them unless it improves the readability.
This is preferred:
This is also okay:
You can use additional comments with
//. These can be above what it is describing or to the side. Try to remain consistent in what you are commenting. Do not use
/* */. You can align comments on the side or not, whichever improves readability.
This is correct:
This is wrong:
Periods are optional for comments, but recommended if it’s a proper sentence. However, remain consistent in whatever file or section you are commenting.
This is correct:
This is wrong:
Mentioning other files in the repo
To mention another contract file in the repo use the standard like this:
If you are referring to some struct or function within the file you can use the standard like this:
To document the implementing contract of an interface, you cannot use
@inheritdoc, it is not supported for contracts. Thus, you should mention a statement like so:
You can then mention implementation specific details by adding a
Documenting internal functions and structs
Internal functions and structs should commented with a
@dev tag, and you can also comment the contents of the struct with explanatory comments.
Documenting user-facing functions versus internal functions
All user-facing functions should be fully documented with NatSpec. Internal functions should always be commented with a
@dev tag, not a
Explanatory comments use
//. There is a common idea that the code describes the documentation. There are pros to this approach. One of the pros is that you remove the coupling between documentation and the code it’s describing, that’s why we should always strive for the minimum viable documentation (one of our core documentation philosophies). It can also appear cleaner.
It’s important that our codebase is well documented with explanatory comments. Thus, in addition to the standard NatSpec documentation which we should apply, we should comment the more complex things in our codebase for higher readability. More important than commenting what we should be concerned with commenting why. The what does not need to be commented for obvious things, of course the code is able to achieve that. We should comment the what for more complex things to aid in the reader for more quickly understanding the code. In addition to that, we should strive to answer the why with comments in our code.
Keep in mind the advantage of having minimum viable documentation. Keep the comments close to the code which it is describing, so that it does not easily go stale or out of date.
There are several annotations used in NatSpec, this is the order of precedence we use from top to bottom:
- @author [we don’t use this tag]
- @custom [we don’t use this tag unless we define the convention for it here]
This section describes our documentation standards at Taiko.
- Create the minimum viable documentation.
- Don’t repeat yourself, use links to existing documentation or inherit it.
- Keep documentation close to what it’s describing (for example, in the source code).
Use the Microsoft Writing Style Guide as a base point of reference for writing style. Generally, don’t worry too much about things like typos. What’s more important is following the basic philosophies outlined above and following structural standards for highly readable and minimal documentation.
If you are interested in creating some content (video, blog post, tweet thread, visuals, etc.), you are absolutely free to do so. It’s useful to get a peer review on these, if you need a peer review please reach out to the community / team on the Taiko Discord.
If you are looking for some more guidance on creating content, you can consult the Taiko content guide.