Skip to content

Home

Jump to bottom Edit New page
Larz Conwell edited this page Jan 9, 2014 · 6 revisions

Sphia Contribution Guide

Sphia welcomes new contributors with open arms. This guide will help you get started. It is recommended that one be familiar with the Sophia API. See the Sophia documentation for more information.

Table of Contents

  1. Core Contribution
  2. Git Conventions
  3. Fork Development
  4. Coding Conventions
  5. Feature Development
  6. Tests
  7. Merges into Master
  8. Releases
  9. Community
  10. Project Maintainers

Core Contribution

The core development team is charged with maintaining the integrity of Sphia's development, which includes features, process, code, and documentation. If you are interested in becoming a core contributor please email jwerle or stephenmathieson. It is at the will of the core contributors for pull requests from other contributors to be merged into a branch. Each core member should conform and uphold this guide.

Git Conventions

It is important to maintain a consistent development work flow. This will outline the simple, yet important process for development contributions.

Prerequisites

Git needs to know how you are. You can configure your user.name and user.email properties globally, or local to the repository.

Global
$ git config --global user.name "First Last"
$ git config --global user.email "[email protected]"
Local
$ cd /path/to/sphia-clone
$ git config user.name "First Last"
$ git config user.email "[email protected]"

Branch

Branches should be named to either represent the feature they implement, test they pass or fail, or issue the close.

Feature

Feature branches should be named to represent the feature they implement.

$ git checkout -b my-feature-branch -t origin/master
Test

Test branches should be named to show whether the test they implement passes or fails.

$ git checkout -b set-fails-unterminated-string -t origin/master
Issues

Issue branches should be named with an obvious intent, such as fixes-unterminated-string.

$ git checkout -b fixes-unterminated-string -t origin/master

Commits

Commit logs represent a summary of changes in time in a human-readable way. This is important because it describes changes over time and why.

Feature branch commits

When committing to your own feature branch make sure your messages are concise. A good guideline borrowed from libuv's contribution guide:

  1. The first line should be 50 characters or less and contain a short description of the change prefixed with the name of the branch/feature/etc.
  2. Keep the second line blank.
  3. Wrap all other lines at 70 columns.

An example of a thorough commit message:

feature: explaining the commit in one line

Body of commit message is a few lines of text, explaining things
in more detail.

The body of the commit message can be several paragraphs, and please do proper word-wrap and keep columns shorter than about 70 characters or so.

git log will show things nicely even when it is indented.

The header line should be meaningful. It is what other people see when they run git shortlog or git log --oneline and should explain the point of the commit.

Check the output of git log --oneline files_that_you_changed to find out what your changes touch.

Rebase

Use git rebase, not git merge to sync your branch over time:

$ git fetch upstream
$ git rebase upstream/master

Fork Development

The following code examples and content is for a fork of the main Sphia repo.

To contribute to a Sphia project fork it on Github and add an upstream remote for the Sphia repo:

$ git clone https://github.com/username/sphia.git
$ cd sphia
$ git remote add upstream https://github.com/sphia/sphia.git

Merging via Pull Request

Now decide if you want your feature or bug fix to go into the master branch or the stable branch. As a rule of thumb, bug fixes go into the stable branch while new features go into the master branch.

Create Pull Request

Go to https://github.com/username/sphia and select your feature branch. Click the 'Pull Request' button and fill out the form to begin the merge process

Review

Sphia pull requests are reviewed within a few days unless urgent issues consume resources. If there are comments to address, please do.

If code changes are required, please apply your changes in a separate commit and push that to your feature branch. When you are ready for an other review, post a comment in the pull request.

Note: GitHub does not send out notifications when you add commits

Coding Conventions

In general, our coding conventions will align with the Google C/C++ style guide, but a few other points are to be noted:

  • All symbol names should be descriptive and concise.

  • All publicly available symbols should be prefixed with sphia_ or SPHIA_ for macros.

  • Always use two spaces and not tabs.

  • Lines should be wrapped at 80 characters.

  • Ensure that lines have no trailing whitespace, and use unix-style (LF) line endings.

  • In most cases, variables should only be declared at the top of a scope (function, if/for/while-block).

  • Use properly constructed sentences when writing comments or documentation.

  • When documenting APIs and/or source code, don't make assumptions or make implications about race, gender, religion, political orientation or anything else that isn't relevant to the project.

Feature Development

When creating a feature it is important to open an issue first for discussion. This is important because it would suck to see your time and work wasted because a discussion didn't happen to see if the feature aligned with the project goals/timeline.

Core Feature

Core features are features that live in the source code of sphia itself, such as init, get, and set. Core features must always have a corresponding discussion with majority buy in from the core development team. These features should exist in src/ unless otherwise discussed.

Plugin Feature

A plugin feature is a feature intended to augment the use of sphia. An example is sphia-transaction that provides the sphia transaction command. It makes use of sophia transaction functions.

$ sphia transaction --path /tmp/db
sphia> begin
sphia> set --key "foo" --value "bar"
sphia> commit

The sphia-batchput is also an example of a sphia plugin. It makes use sophia functions to enable a batch set of key-value pairs.

$ sphia batchput --path /tmp/db key1 value1 key2 value2 key3

Tests

Bug fixes and features should come with tests. Add your tests in the test/ directory. Check out the other tests to see how they should be structured. The test/sphia-test.h macro defines macros and a global sphia_t * for use in tests.

Your tests should be .c files and executable from the root of the repository with:

$ make test

Merges into Master

Merges to master are orchestrated via Pull Requests. All pull requests are reviewed and require majority buy in before a merge.

Releases

All Releases are tagged and should have a corresponding branch.

Community

You can start getting involved by using sphia today.

Links

Have you found a bug, want to make an improvement or suggestion? Create an issue in the projects repo page.

Contributors and Maintainers

If you'd like to see the list of contributors for a Sphia project visit the repos graph page and view the contributors graph.

A list of Sphias maintainers can be found here.

Add a custom footer
Add a custom sidebar
Clone this wiki locally