Skip to content

Latest commit

 

History

History
155 lines (99 loc) · 6.41 KB

getting-started.md

File metadata and controls

155 lines (99 loc) · 6.41 KB
Raw

Helpful Resources

  • The Project Readme includes a crash-course for getting setup with the code and running a few tests
  • The Contribution Guide includes more thorough discussion of the project's guiding principles, governance model, and how to get involved
  • The Technical Reference includes documentation for the code itself and how it works
  • Code immediately merged may take a few minutes to go live as the docs get generated and page cache is cleared
  • The Architecture Guide walks through the data model of transactions and the currently-implemented architectures
  • The Contribution Lifecycle Guide takes you through what you can expect throughout the process of submitting a contribution to OpenCBDC

Frequently Asked Questions

What does a good commit look like?

A good commit message clearly communicates the goal of the included changes (the why rather than the what). Chris Beams wrote a great article on writing good commit messages.

A commit's contents should be very focused on accomplishing a single task (e.g., fixing a single bug). In particular, you should strive for your commits to be atomic.

If there is an issue open that your contribution addresses, reference that issue number in the commit message's body text.

How do I sign-off on my contributions?

OpenCBDC uses a developer certificate of origin (or DCO) to ensure that all contributions are made freely available under the same license as OpenCBDC's original code base. To do that, when contributors submit code (or other changes that are reflected in any repository), they are required to “sign-off” their commits.

To sign off, you can just add the -s argument when you create your commit with git commit (i.e., use git commit -s). This adds the following line to the bottom of your commit:

Signed-off-by: Your Name <[email protected]>

(You could manually type this out if you want to.)

I've already created commits but forgot to add sign-offs; how do I fix them?

There are several options to add sign-offs retroactively:

--amend your most-recent commit

If you only need to change the last commit you made, you can do the following:

$ git commit --amend --no-edit --signoff
$ git push --force origin <your-branch-name>

rebase all the commits in your contribution (requires git version 2.13 or newer)

If you need to add a sign-off to each of the commits in your contribution, you can use git rebase to automatically add it to each one:

$ git rebase --signoff HEAD~X # replace X with the number of commits in your contribution
$ git push --force origin <your-branch-name>

interactive rebase

If your version of git is older than 2.13 or you only need to add sign-offs to particular commits in your contribution, you can use an interactive rebase to choose the commits to modify:

$ git rebase -i HEAD~X # replace X with the number of commits in your contribution

A text editor will open showing your commits (make sure only your commits are listed; if not, exit the file, and rerun the rebase command with the correct value for X). Mark all the commits that need a sign-off as “reword”. The rebase will stop at each of these commits and let you run commands.

Run these two commands until the rebase is complete:

$ git commit --amend --no-edit --signoff
$ git rebase --continue

Now, force-push your branch:

$ git push --force origin <your-branch-name>

Can I contribute without using docker (running some other environment, etc.)?

Absolutely! However, we only officially support the included docker compose files (as they mirror our automated test environment).

After cloning the code, scripts/install-build-tools.sh needs to be ran just once. It will attempt to install the necessary software tools upon which the project relies on.

Then, scripts/setup-dependencies.sh should be run to install libraries and dependencies to will attempt to configure your environment.

Note: scripts/install-build-tools.sh only supports Ubuntu-based linux distributions and macOS (which depends on Homebrew). However, it can be used as a guide to understand what you must do to get your environment setup.

In short, scripts/install-build-tools.sh does the following:

  • installs a couple packages needed for building and testing (e.g., clang, LLVM, cmake, make, lcov, googletest, git)
  • installs the external dependencies:
  • downloads a helper python script to run code linting and static analysis

Note: The code assumes it is running on Linux on an x86_64 processor. However, we generally tend towards keeping code portable, so any *nix-like operating system on an x86_64 processor may function well.

What can I do to make it more likely my code will get merged quickly?

First and foremost, respond to feedback for your contributions quickly and cordially. The faster any issues reviewers bring up are fixed, the faster we can merge your code!

However, here are several things you can do to make review as easy and quick as possible:

  • Keep your working branch up-to-date with our main branch and free of merge conflicts
  • Run ./scripts/lint.sh and ./scripts/test.sh and ensure both succeed before committing changes
  • Run pylint $(git ls-files '*.py') for python code and seek scores close to 10.0.
    • You can use a tool like act to run the CI locally and see if your changes would pass automated-review. act --list to see workflow jobs.
  • Author good commits

Are there easy things for me to get started on?

Definitely! Take a look at our issue tracker's list of good first issues.

Is anyone available to give talks, presentations, or interviews?

Possibly! Please send us an email with your questions or requests and we will get back to you as soon as possible!