Leo
Leopold Schabel
parent
669653ccc4
commit
7e59627c96
|
|
@ -1,3 +0,0 @@
|
|||
[gerrit]
|
||||
defaultremote=origin
|
||||
defaultbranch=dev.v2
|
||||
103
CONTRIBUTING.md
103
CONTRIBUTING.md
|
|
@ -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.
|
||||
|
|
|
|||
14
DEVELOP.md
14
DEVELOP.md
|
|
@ -79,22 +79,16 @@ First, create an SSH key on the VM:
|
|||
ssh-keygen -t ed25519
|
||||
cat .ssh/id_ed25519.pub
|
||||
|
||||
You can then [add your public key on Gerrit](https://forge.certus.one/settings/#SSHKeys) and [clone the repository](https://forge.certus.one/admin/repos/wormhole). The clone command should look like this:
|
||||
You can then [add your public key on GitHub](https://github.com/settings/keys) and clone the repository:
|
||||
|
||||
```shell
|
||||
# don't copy this - copy it from Gerrit instead
|
||||
git clone "ssh://yourusername@forge.certus.one:30322/wormhole" && scp -p -P 30322 yourusername@forge.certus.one:hooks/commit-msg "wormhole/.git/hooks/"
|
||||
```
|
||||
git clone git@github.com:certusone/wormhole.git
|
||||
|
||||
Configure your Git identity to match your Gerrit name and email:
|
||||
Configure your Git identity:
|
||||
|
||||
git config --global user.name "Your Name"
|
||||
git config --global user.email "yourname@company.com"
|
||||
|
||||
*If you are a Jump Crypto employee, make sure to log into Gerrit using Azure SSO using your
|
||||
jumptrading.com email address and request Gerrit review permissions in #wormhole-dev on Slack.*
|
||||
|
||||
You can then use our regular Git and Gerrit workflow as detailed in [Submit change for review](CONTRIBUTING.md#submit-change-for-review).
|
||||
Your email address should be linked to your personal or company GitHub account.
|
||||
|
||||
### Set up devnet on the VM
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
gerrit: https://forge.certus.one
|
||||
issuerepo: certusone/wormhole
|
||||
parent-branch: main
|
||||
branch: dev.v2
|
||||
Loading…
Reference in New Issue