-
Notifications
You must be signed in to change notification settings - Fork 0
Home
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.
- Core Contribution
- Git Conventions
- Fork Development
- Coding Conventions
- Feature Development
- Tests
- Merges into Master
- Releases
- Community
- Contributors and Maintainers
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.
It is important to maintain a consistent development work flow. This will outline the simple, yet important process for development contributions.
Git needs to know how you are. You can configure your user.name and user.email properties globally, or local to the repository.
$ git config --global user.name "First Last"
$ git config --global user.email "[email protected]"$ cd /path/to/sphia-clone
$ git config user.name "First Last"
$ git config user.email "[email protected]"Branches should be named to either represent the feature they implement, test they pass or fail, or issue the close.
Feature branches should be named to represent the feature they implement.
$ git checkout -b my-feature-branch -t origin/masterTest branches should be named to show whether the test they implement passes or fails.
$ git checkout -b set-fails-unterminated-string -t origin/masterIssue branches should be named with an obvious intent, such as fixes-unterminated-string.
$ git checkout -b fixes-unterminated-string -t origin/masterCommit logs represent a summary of changes in time in a human-readable way. This is important because it describes changes over time and why.
When committing to your own feature branch make sure your messages are concise. A good guideline borrowed from libuv's contribution guide:
- 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.
- Keep the second line blank.
- 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.
Use git rebase, not git merge to sync your branch over time:
$ git fetch upstream
$ git rebase upstream/masterThe 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.gitNow 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.
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
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
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_orSPHIA_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.
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 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.
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> commitThe sphia-batchput command 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 key3Bug 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 testMerges to master are orchestrated via Pull Requests. All pull requests are reviewed and require majority buy in before a merge.
All Releases are tagged and should have a corresponding branch.
You can start getting involved by using sphia today.
Have you found a bug, want to make an improvement or suggestion? Create an issue in the projects repo page.
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.