|
|
@@ -9,13 +9,13 @@ and code reviews are our most important tools to accomplish that.
|
|
|
- All new features must first be discussed in a GitHub issue before starting to implement them. For
|
|
|
complex features, it can be useful to submit a [formal design document](design/template.md).
|
|
|
|
|
|
-- Development happens on a long-lived development branch (usually `main` or `dev.<x>` for larger changes).
|
|
|
- Every change going into a development branch is reviewed individually (see below). Release branches branched
|
|
|
- from `main` are used to support in-the-wild releases of Wormhole. We aim to support at most two release
|
|
|
+- Development happens on a long-lived development branch (`dev.v2` and `dev.v1`).
|
|
|
+ Every change going into a development branch is reviewed individually (see below). Release branches may be used
|
|
|
+ to support in-the-wild releases of Wormhole. We aim to support at most two release
|
|
|
branches at the same time. Changes can be cherry-picked from the development branch to release branches, but
|
|
|
never from release branches to a development branch.
|
|
|
|
|
|
-- Releases are first tested on a testnet. This involves coordination with the mainnet DAO running the nodes.
|
|
|
+- Releases are first tested on a testnet.
|
|
|
|
|
|
- Commits should be small and have a meaningful commit message. One commit should, roughly, be "one idea" and
|
|
|
be as atomic as possible. A feature can consist of many such commits.
|
|
|
@@ -30,6 +30,8 @@ and code reviews are our most important tools to accomplish that.
|
|
|
Documentation for the in-the-wild deployments lives in the
|
|
|
[wormhole-networks](https://github.com/certusone/wormhole-networks) repository.
|
|
|
|
|
|
+See [DEVELOP.md](./DEVELOP.md) for more information on how to run the development environment.
|
|
|
+
|
|
|
## Contributions FAQ
|
|
|
|
|
|
### Can you add \<random blockchain\>?
|
|
|
@@ -64,96 +66,3 @@ of communication (like transfers). It is likely that you can use the existing Wo
|
|
|
own features on top of, without requiring any changes in Wormhole itself.
|
|
|
|
|
|
Please open a GitHub issue outlining your use case, and we can help you build it!
|
|
|
-
|
|
|
-## Submit change for review
|
|
|
-
|
|
|
-Certus One uses **Gerrit** for code review on [**forge.certus.one**](https://forge.certus.one). Gerrit has the
|
|
|
-advantage of dealing with a stack of individual commits, rather than reviewing an entire branch. This makes it
|
|
|
-much easier to review large features by breaking them down into smaller pieces, and puts a large emphasis on
|
|
|
-clean commits with meaningful commit messages. This workflow helps us write better software.
|
|
|
-
|
|
|
-We do not currently accept GitHub pull requests.
|
|
|
-
|
|
|
-The GitHub repository is a mirror of the Gerrit repository. GitHub has a global CDN for Git, so if you plan
|
|
|
-to clone the Wormhole repo a lot in an automated fashion, please clone it from GitHub.
|
|
|
-
|
|
|
-### Why Gerrit?
|
|
|
-
|
|
|
-With GitHub, if you want to submit three changes A, B and C to be reviewed (in that order), you have two
|
|
|
-choices:
|
|
|
-
|
|
|
-- Submit a single PR with carefully rebased commits, and ask the reviewer to actually look at your
|
|
|
- carefully-written commit messages and review each commit individually. However, this is not well-supported
|
|
|
- by the UI, approval can only be given for the whole stack, and rebasing/adding commits breaks it altogether.
|
|
|
- It also doesn't work with the squash merge policy used by many projects.
|
|
|
-
|
|
|
-- Submit three individual PRs with different bases. This allows you to approve and merge each change
|
|
|
- individually, but requires you to manually rebase multiple branches on top of each other, which is annoying.
|
|
|
-
|
|
|
-By making it hard to break changes up into smaller pieces, GitHub encourages large, hard-to-review changes.
|
|
|
-With Gerrit, the opposite is true - it's **trivial to submit a stack of changes**. You can just put your
|
|
|
-changes A, B and C on a single branch:
|
|
|
-
|
|
|
- C <-- HEAD
|
|
|
- ↑
|
|
|
- B
|
|
|
- ↑
|
|
|
- A
|
|
|
- ↑
|
|
|
- O <-- origin/main, main
|
|
|
- ↑
|
|
|
- …
|
|
|
-
|
|
|
-... and submit all three using a single `git push origin HEAD:refs/for/main`. Gerrit will create a review
|
|
|
-request for A, B and C, and it understands the relation chain between them. C can only be merged after B and
|
|
|
-C, and merging C will automatically merge B and C as well.
|
|
|
-
|
|
|
-This means that A can be reviewed, approved and merged before B and C are done. Other team members can then
|
|
|
-start building on A and avoid a "big scary merge". This workflow is often called **trunk-based development**.
|
|
|
-
|
|
|
-Other advantages of Gerrit include:
|
|
|
-
|
|
|
-- The ability to **compare different versions of a change**, with inline comments shown in their original place.
|
|
|
- This is very useful when re-reviewing a change.
|
|
|
-- Keeping inline comments across rebases (!).
|
|
|
-- Very responsive user interface that can be fully driven using keyboard shortcuts.
|
|
|
- GitHub can be slow - opening a PR and showing the diff often takes multiple seconds.
|
|
|
-- A view that shows an overview of open comments, their status and a small code snippet.
|
|
|
-- Comments can be attached to a selection, not just entire lines.
|
|
|
- Multiple threads can be attached to the same line.
|
|
|
-- The "**attention set**" mechanism with a fine-grained state machine on who needs to take action,
|
|
|
- which avoids sending non-actionable email notifications!
|
|
|
-- We run our own infrastructure. Yay decentralization!
|
|
|
-
|
|
|
-### Quickstart
|
|
|
-
|
|
|
-You can log into Gerrit using your Google account. **If you're contributing on behalf of a company, make
|
|
|
-sure that your Git email address reflects your affiliation!**
|
|
|
-
|
|
|
-First, add your SSH keys to Gerrit in your [profile settings](https://forge.certus.one/settings/#SSHKeys).
|
|
|
-Alternatively, you can generate an HTTP Password and store it in your [Git credentials store of
|
|
|
-choice](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage) - this is particularly useful for
|
|
|
-development hosts or corporate environments that can't use SSH or access your key.
|
|
|
-
|
|
|
-**Clone the repo from Gerrit** if you haven't done so already by going to the [repository
|
|
|
-page](https://forge.certus.one/admin/repos/wormhole) and using the *"Clone with commit-msg hook"* command. If
|
|
|
-you have an existing GitHub checkout you want to convert, you can simply set a new remote and you'll be
|
|
|
-prompted to install the hook the first time you push to Gerrit:
|
|
|
-
|
|
|
- git remote set-url origin ssh://<gerrit-username>@[...]
|
|
|
-
|
|
|
-Then, just commit to a local branch. Every local commit becomes one code review request. Multiple commits on
|
|
|
-the same branch will be submitted as a stack (see above). Once you're done, push to the special ref that
|
|
|
-creates your code reviews:
|
|
|
-
|
|
|
- git push origin HEAD:refs/for/main
|
|
|
-
|
|
|
-(replace `main` by a different development branch, where applicable)
|
|
|
-
|
|
|
-That's it! No special tooling needed. You can now go look at your commits in the web UI and add reviewers. If
|
|
|
-you want less typing, take a look at these:
|
|
|
-
|
|
|
-- There's an excellent [IntelliJ plugin](https://plugins.jetbrains.com/plugin/7272-gerrit) that allows you to clone,
|
|
|
- check out and even review CLs from inside your IDE.
|
|
|
-
|
|
|
-- The Go project's [git-codereview](https://pkg.go.dev/golang.org/x/review/git-codereview) CLI utility.
|
Leo