Skip to main content

Code

The Enarx project welcomes contributions!

Would you like to help with the development of Enarx?

This page will guide you towards submitting your first pull request.

There are many different skills needed to build Enarx, from low-level assembly code for platform-specific enablement (think SGX, SEV, etc.) to kernel-related work, from WebAssembly to building and maintaining our infrastructure and automated integration and testing (CI/CD), and more, so please don't hesitate to try your hand at any of these or to come and talk to us.

You will find good first issues to work on in our issue tracker, labelled "good first issue".

Note on issue and bug tracking​

To get a better understanding of how we track issues and bugs, we recommend you also read the How to contribute: bug reporting page.

  1. Code of Conduct
  2. Contributing code: general process
    1. First Steps
    2. Developer Certificate of Origin
    3. Coding Style
    4. Development Environment set up
    5. Enarx Lab machines

Code of Conduct​

The Enarx project aims to be a welcoming and inclusive community, and to this end adheres to and enforces the Contributor Covenant code of conduct. You can read it here.

Code​

First steps​

Using Rust and Git​

If you've never programmed in Rust, don't worry, we've all been here. It can be very challenging to ramp up on a project without first being familiar with the programming language it uses Furthermore, being familiar with version control software (Git) is a critical skill to have for collaborating with others.

Here are some of our favourite resources for learning Git and Rust:

  • The Book & other official resources
  • Programming Rust - This book is not free, but some of us like it very much.
  • Pro Git 2nd Edition - You can get very far with git by just reading Chapters 2, 3, and 5.
  • Once you've got the basics of Git, a good skill to develop is how to create atomic commits. These might also appear in search results as "logical commits".

Methodology​

If you've never contributed code to an open source project, this page will walk you through the whole process and should be very helpful.

Contributing code to the Enarx project follows this overall methodology:

  1. fork the code to your account
  2. make improvements
  3. publish them to your account
  4. submit improvements using a Pull Request (PR)
    1. make changes as required
  5. repeat

With this general plan in mind, there are a few more recommendations you should follow:

  1. make sure that everything you're doing is in GitHub. It doesn't matter if it's not perfect. Churn is expected, but we need the code there to start with.
  2. ensure that no single issue should take more than 1-2 days to complete. If you have an issue that will take more time, then break it down into separate issues, and link them (under the top issue if required).
  3. only have 1-3 issues assigned to you at any time.
  4. when you complete an issue, submit a PR. Mention that issue in the PR ("closes #123")
  5. review other folks' PRs.

We are always willing to discuss ways to improve this set of guidelines, if for any reason you feel they aren't working.

Developer Certificate of Origin​

Enarx uses the Developer Certificate of Origin (DCO) to help check that contributors are allowed to make a contribution and that as an open source project, Enarx has the right to distribute them under its license (Apache Licence 2.0).

In practice, this means code committed to the project must be signed-off, using git commit -s, which will result in a commit message ending in something like:

Signed-off by Nathaniel McCallum nathaniel@profian.com

You can read the text of the DCO on the DCO's website. (We also host a copy of the text in one of our repos.)

Coding style​

We adhere to upstream Rust coding style guidelines. For more information about the Enarx coding style, please refer to our documentation on this subject.

Enarx Development Environment set up​

These instructions are still a bit minimal, we will make them more complete in the near future.

Note: we have some lab machines available. More information on how to access and use them on the Lab page.

Fedora, Red Hat Enterprise Linux (RHEL)​

openssl-devel package can be installed like so:

# dnf install openssl-devel

Two Perl packages (which are openssl dependencies) also need to be installed thus:

# dnf install perl-FindBin perl-File-Compare

musl packages are now included in Fedora. However, they need to be enabled on RHEL like so:

# dnf copr enable taocris/musl

musl packages can be installed on Fedora and RHEL like so:

# dnf install musl-devel musl-libc-static musl-gcc musl-clang

Debian, Ubuntu​

You will need these additional packages:

  • libssl-dev
  • musl-dev
  • musl-tools

To install:

# apt install libssl-dev musl-dev musl-tools

Rust​

If Rust is not already installed, please visit rustup.rs and follow the Rust project's official quickstart instructions to install it. It's possible that Rust might be packaged for your favorite operating system, but rustup provides a number of well-supported features for managing the Rust toolchain and is a preferred and trusted channel for keeping the toolchain updated beyond what might be available in the package repositories.

With the Rust toolchain installed, add the required target platform like so:

$ rustup target add x86_64-unknown-linux-musl

For Ubuntu, we must also install Rust Nightly as below:

$ rustup toolchain install nightly-x86_64-unknown-linux-gnu
$ rustup toolchain install nightly

Git environment set up​

You will also need to set up your git environment if you haven't already done so.

Here are a few pointers to help you set it up.

On the Github side​

  • Ensure you have an SSH key set up. If you do not, you can generate one with the following command:
    • ssh-keygen -t ed25519 -C "$(whoami) on $(hostname), generated on $(date -I)" Then add it to your Github profile.
  • Fork the desired repo on github.com to your user, to be able to work on your own version of the code before submitting it. On any given repo, say enarx/enarx, use the "fork" button at the top right to create a copy of the repo in your Github account.

On your local machine​

  • If you have not already done so, set your username and email:
    • git config --global user.name "your name"
    • git config --global user.email "name@example.com"
  • Clone your fork locally:
    • git clone https://github.com/<your_username>/<enarx_repo>
  • Add an "upstream" remote to your local git repo:
    • git remote add upstream https://github.com/enarx/<enarx_repo.git>
  • To check the remote repositories: git remote -v

Working on the code​

  • Create a branch for your work:
    • git checkout -b <your_working_branch>
  • Make your changes, then add the changed files to the staging area:
    • git add <file> (or git add -a to take into account all modified files, including deletions)
  • Commit your changes (the "-s" is to sign-off your commits, cf. DCO section)
    • git commit -s -m "commit message here"
  • Push your changes:
    • git push
  • If this is your first commit on your new branch, you will need to create the new branch remotely before pushing to it. This can all be done in one command with: git push --set-upstream origin <your-branch-name>. Git should suggest this as a command when a regular push fails.

With this, your code is visible in your personal repo on GitHub and can be shown to others, for instance.

Contributing your code​

When you consider your code to be ready, you can make a request for that code to be reviewed and, if all goes well, merged into the main code base: a Pull Request (or PR). More info on the pull request process can be found here.

How often to commit, how often to make pull requests?​

Our recommendation is to commit incrementally, whether it works or not, and to push it to your personal repo.

When your code is at a point at which you're ready to merge it, squash all the "stream of consciousness" commits into a series of logical commits. This helps maintain a history of code changes that is both truthful and readable to others.

Also, make sure that your commit messages follow these conventions in order to be clear and maintainable: How to Write a Git Commit Message.

Keeping your code up to date with the project's code​

As the project keeps moving, the code base will change. Once changes have been made to the Enarx repo, to keep your local version of the code up to date:

  • Sync the fork:
    • git fetch upstream
  • Ensure you are on your main branch:
    • git checkout main
  • Make sure your local main branch is up to date with the upstream (that any commits you've made that aren't already in upstream/main are replayed on top of that other branch):
    • git rebase upstream/main

From then on, you can go on to making changes again on your working branch, committing them etc..

Enarx Lab machines​

We have some lab machines available. More information on how to access and use them on this Lab page.