Thank you for looking to contribute to the GNO project. We appreciate every open-source contribution, as it helps us improve and enhance gno for the benefit of the community.
This document outlines some basic pointers on making your future contribution a great experience. It outlines basic PR etiquette employed by the core gno team. It lays out coding styles, simple how-to guides and tools to get you up and running and pushing code.
If you are unsure about something, please don’t hesitate to reach out for help by opening an issue here or discuss on Discord. Likewise, if you have an idea on how to improve this guide, go for it as well.
- Discord - we are very active on Discord. Join today and start discussing all things gno with fellow engineers and enthusiasts.
- Awesome GNO - check out the list of compiled resources for helping you understand the gno ecosystem
- Active Staging - use the currently available staging environment to play around with a production network. If you want to interact with a local instance, refer to the Local Setup guide.
- Twitter - follow us on Twitter to get the latest scoop
- Telegram - join our official Telegram group to start a conversation about gno
The gno repository is primarily based on Golang (Go), and Gnolang (Gno).
The primary tech stack for working on the repository:
- Go (version 1.19+)
- make (for using Makefile configurations)
- Docker (for using the official Docker setup files)
It is recommended to work on a Unix environment, as most of the tooling is built around ready-made tools in Unix (WSL2 for Windows / Linux / macOS).
For Gno, there is no specific tooling that needs to be installed, that’s not already provided with the repo itself.
You can utilize the gnodev command to facilitate Gnolang support when writing Smart Contracts in Gno, by installing it
with make install gnodev.
Additionally, you can also configure your editor to recognize .gno files as .go files, to get the benefit of syntax
highlighting.
Currently, we support a Visual Studio Code extension (eventually official in the future) for Gnolang.
Add to your .vimrc file:
function! GnoFmt()
cexpr system('gofmt -e -w ' . expand('%')) "or replace with gofumpt
edit!
endfunction
command! GnoFmt call GnoFmt()
augroup gno_autocmd
autocmd!
autocmd BufNewFile,BufRead *.gno set filetype=go
autocmd BufWritePost *.gno GnoFmt
augroup END- Install go-mode.el.
- Add to your emacs configuration file:
(add-to-list 'auto-mode-alist '("\\.gno\\'" . go-mode))To get started with Gno development, the process is relatively straightforward.
Clone the repo:
git clone https://github.com/gnolang/gno.git
Build / install base commands:
make build
That’s it!
There are essentially 2 ways to execute the entire test suite:
- Using the base
go testcommands (running locally), - Using a tool like act to run workflow files in Docker containers
To run the entire test suite locally, run the following command:
make test
This will execute the full test suite, that includes tests for .gno files, as well as project .go tests.
Using a tool like act can enable you to run specific repository workflow files locally,
using Docker. The workflow configurations contain different go versions, so it might be worth running if you’re
worried about compatibility.
To run the entire test suite through workflow files, run the following command:
act -v -j go-test
If you wish to test a .gno Realm or Package, you can utilize the gnodev tool.
- To install it, simply run:
make install gnodev
- Now, you can point to the directory containing the
*_test.gnofiles:
gnodev test <path-to-dir> --verbose
To learn more about how gnodev can help you when developing gno code, you can look into the available
subcommands by running:
gnodev --help
The repository structure can seem tricky at first, but it’s simple if you consider the philosophy that the gno project employs (check out PHILOSOPHY.md).
The gno project currently favors a mono-repo structure, as it’s easier to manage contributions and keep everyone aligned. In the future, this may change, but in the meantime the majority of gno resources and source code will be centralized here.
cmd- contains the base command implementations for tools likegnokey,gnotxport, etc. The actual underlying logic is located within thepkgssubdirectories.examples- contains the example.gnorealms and packages. This is the central point for adding user-defined realms and packages.gnoland- contains the base source code for bootstrapping the Gnoland nodepkgs- contains the dev-audited packages used throughout the gno codebasestdlibs- contains the standard library packages used (imported) in.gnoSmart Contracts. These packages are themselves.gnofiles.tests- contains the standard language tests for Gnolang
Pull Requests serve primarily as an addition to the codebase, but also as a central point of discussion for potential features. Instead of opening issues, contributors are encouraged to open PRs with their suggested changes, however small, in order to get feedback from the community on their work.
The key to successfully submitting upstream changes is providing the adequate context, with the correct implementation, of course.
To let the core team know about what your PR does, and why it does it, you should take a second to fill out one of two PR templates provided on the repo.
Once someone leaves a PR review (with open comments / discussions), it is on the PR creator to do their best in trying
to resolve all comments.
The PR reviewer is in charge of resolving each conversation (hitting the Resolve Conversation button), after the PR
creator implements or discusses
the requested changes.
If the PR creator pushed code as a result of some conversation, they should link the commit hash in the relevant comment reply, ex:
Fixed in:
[0a0577c](https://github.com/gnolang/gno/commit/0a0577ccdeb951a6621d6fbe1c04ac4e64a529c1)Avoid rebasing after you open your PRs to reviews. Instead, add more commits to your PR. It's OK to do force pushes if PR was never opened for reviews before.
A reviewer may like to see a linear commit history while reviewing. If you tend to force push from an older commit, a reviewer might lose track in your recent changes and will have to start reviewing from scratch.
Don't worry about adding too many commits. The commits are squashed into a single commit while merging (if needed).
The base PR template is by default a simple template meant to illustrate quickly what’s the context of the PR. Here, you should describe your PR in detail, and leave a remark as to how your changes have been tested.
If you've run a manual test, please provide the exact steps taken.
The detailed PR template is used when you want to convey a bit more detail and context for your PRs. In contrast to the default PR template, it follows a checklist approach that is meant to be filled out by the PR creator, with as much information as possible. These detailed PR descriptions serve an important purpose down the line in the future, when it’s important to understand the context under which a PR has been created, and for what reason.
You can utilize the detailed PR template by appending the following query param to the URL on the new PR page:
template=detailed_pr_template.md
Found something funky while using gno? You can report it to the team using GitHub issues.
Before opening an issue, please check for existing open and closed Issues to see if that bug/feature has already been reported/requested. If you find a relevant topic, you can comment on that issue.
In the issue, please provide as much information as possible, for example:
- what you’ve experienced
- what should be the expected behavior
- which version of gno are you running
- any logs that might be relevant
Once you open up an issue, a core team member will take a look and start a conversation with you about resolving it.
The gno project operates in the public. This means that feature requests are not just reviewed by the core team, but also by the general user base and other contributors.
If you would like to propose a new feature (submit a feature request), you can do so by opening up an issue on GitHub, and providing ample context as to why this feature should be implemented. Even better, if you are able to propose your feature request in code, you should open a PR instead. This allows the community to easily discuss and build upon the idea in a central place.
Additionally, it is encouraged that users suggest their idea on the official communication channels like Discord, to get a feel for what other contributors think.
The gno project tends to use the Conventional Commits standard for any
commit that goes into the main code stream (currently, the master branch).
Each PR is squashed and merged into the main code stream, which means PR titles should adhere to the Conventional Commit standard, and be short and precise.
A general rule of thumb:
- Use Conventional Commits for PR titles
- Never favor rewriting history in PRs (rebases have very few exceptions, like implementation rewrites; see A Word on Rebasing)
- Tend to make separate commits for logically separate changes
The gno codebase currently doesn’t follow any specific standard in terms of code style. The core team, and core contributors, favor using the following code style guides:
If unsure, you should always follow the existing code style of the repository.
Additionally, the gno codebase uses linters to enforce some common coding style etiquette. Any PR that aims to modify the gno codebase should make sure that the linter checks pass; otherwise they won’t be merged into the main code stream.
When writing in-code documentation, always favor to stay aligned with the godoc standard. Gno’s development philosophy stays true to idiomatic Go, and this transfers to the documentation as well.
Resources for idiomatic Go docs:
The gno project uses a set of labels for managing ongoing issues and pull requests.
If you’d like to modify the current label structure, please submit a PR modifying the labels.json file. The gno project utilizes automatic label management.
| Label Name | Description |
|---|---|
| breaking change | PR introduces backwards incompatible functionality |
| bug fix | PR introduces a fix for a known bug |
| dependencies | PR introduces a package version bump |
| documentation | PR introduces an improvement or addition to the docs |
| don’t merge | PR contains unstable functionality that shouldn't be merged yet |
| feature | PR adds new functionality to Gno |
| hotfix | PR applies a hotfix that should be merged ASAP |
| Label Name | Description |
|---|---|
| bug | Issue confirms a bug is present in Gnoland |
| duplicate | Issue already exists, or has been posted before |
| good first issue | Issue is a great introduction for newcomers |
| help wanted | Issue requires extra attention from the community |
| info needed | Issue is lacking information needed for resolving |
| investigating | Issue is still being investigated by the team |
| question | Issue starts a discussion or raises a question |
Notable contributions of fixes/features/refactors:
- #208 - @anarcher, gnodev test with testing.T
- #167 - @loicttn, website: Add syntax highlighting + security practices
- #136 - @moul, foo20, a grc20 example smart contract
- #126 - @moul, feat: use the new Precompile in gnodev and in the addpkg/execution flow (2/2)
- #119 - @moul, add a Gno2Go precompiler (1/2)
- #112 - @moul, feat: add 'gnokey maketx --broadcast' option
- #110, #109, #108, #106, #103, #102, #101 - @moul, various chores.