diff --git a/CONTRIBUTORS b/CONTRIBUTORS new file mode 100644 index 00000000..c398e536 --- /dev/null +++ b/CONTRIBUTORS @@ -0,0 +1,7 @@ +Contributors +============ + +The following people have contributed to Cement, either by way of source code, +documentation, or testing. + + * BJ Dierkes (aka derks) - Creator, Primary Maintainer diff --git a/ChangeLog b/ChangeLog index 4c61bd81..152e58eb 100755 --- a/ChangeLog +++ b/ChangeLog @@ -27,7 +27,8 @@ Bugs: Features: - None + * :issue:`144` - Added a note on Contributing, as well as a CONTRIBUTORS + file. Incompatible Changes: diff --git a/LICENSE b/LICENSE old mode 100644 new mode 100755 index 91fba8df..802c1ebc --- a/LICENSE +++ b/LICENSE @@ -1,3 +1,5 @@ +.. _license: + License ======= diff --git a/doc/source/contributors.rst b/doc/source/contributors.rst new file mode 120000 index 00000000..0913b7ce --- /dev/null +++ b/doc/source/contributors.rst @@ -0,0 +1 @@ +../../CONTRIBUTORS \ No newline at end of file diff --git a/doc/source/dev/contributing.rst b/doc/source/dev/contributing.rst new file mode 100644 index 00000000..ecad4ab6 --- /dev/null +++ b/doc/source/dev/contributing.rst @@ -0,0 +1,167 @@ +Contributing +============ + +Cement is an open-source project, and is open to any and all contributions +that other developers would like to provide. This document provides some +guidelines that all contributors must be aware of, and abide by to have their +submissions included in the source. + +Licensing +--------- + +The Cement source code is licensed under the BSD three-clause license and is +approved by the `Open Source Initiative `_. All +contributed source code must be either the original work of the contributing +author, which will be contributed under the BSD license, or work taken from +another project that is released under a BSD-compatible license. + +Submitting Bug Reports and Feature Requests +------------------------------------------- + +If you've found a bug, or would like to request a feature please create a +detailed tracker for it at ``_. + +The ideal bug report would include: + + * Bug description + * Include the version of Python, Cement, and any dependencies in use + * Steps to reproduce the bug + * Code samples that show the bug in action + * A pull request including code that a) fixes the bug, and b) atleast one + test case that tests for the bug specifically + + +The ideal feature request would include: + + * Feature description + * Example code, or pseudo code of how you might use the feature + * A pull request including: + * The feature you would like added + * At least one test case that tests the feature and maintains 100% + code coverage when tests are run (meaning that your tests should + cover 100% of your contributed code) + * Documentation that outlines how to use the feature + + + +Guidelines for Code Contributions +--------------------------------- + +All contributors should attempt to abide by the following: + + * Contributors fork the project on GitHub onto their own account + * All changes should be commited, and pushed to your repository + * All pull requests are from a topic branch, not an existing Cement branch + * Contributors make every effort to comply with + `PEP8 `_ + * Before starting on a new feature, or bug fix, always do the following: + * ``git pull --rebase`` to get latest changes from upstream + * Checkout a new branch. For example: + * ``git checkout -b feature/`` + * ``git checkout -b bug/`_ + +The majority of commits only require a single line commit message. +That said, for more complex commits, please use the following as an example +(as outlined in the ProGit link above): + +.. code-block:: text + + Short (50 chars or less) summary of changes + + More detailed explanatory text, if necessary. Wrap it to about 72 + characters or so. In some contexts, the first line is treated as the + subject of an email and the rest of the text as the body. The blank + line separating the summary from the body is critical (unless you omit + the body entirely); tools like rebase can get confused if you run the + two together. + + Further paragraphs come after blank lines. + + - Bullet points are okay, too + + - Typically a hyphen or asterisk is used for the bullet, preceded by a + single space, with blank lines in between, but conventions vary here + +Source Code and Versioning +-------------------------- + +One of the primary goals of Cement is stability in the source code. For this +reason we maintain a number of different git branches for focused +development. + +**Development Branches** + +Active 'forward' development happens out of two branches: + + * master - Development for the next minor stable release. + * portland - Development for the next major release. + +Additionally, specific development branches might exist in the future for +larger releases that may require iterative 'release candidate' handling before +an official stable release. These branches will have the format of: + + * dev/3.1.x + * dev/3.3.x + * dev/4.1.x + * dev/4.3.x + * etc + +**Stable Branches** + + * stable/0.8.x + * stable/1.0.x + * stable/1.2.x + * stable/2.0.x + * stable/2.2.x + * stable/3.0.x + * stable/3.2.x + * etc + +There is a system for versioning that may seem complex, and needs some +explanation. Version numbers are broken up into three parts: + + * .. + +This means: + + * Major - The major version of the source code generally relates to + extensive incompatible changes, or entire code base rewrites. + Applications built on the '1.x.x' version of Cement will need to be + completely rewritten for the '2.x.x' versions of Cement. + * Minor - The minor version signifies the addition of new features. It + may also indicate minor incompatibilities with the previous stable + version, but should be easily resolvable with minimal coding effort. + * Bugfix - During the lifecycle of a stable release such as '2.2.x', the + only updates should be bug and/or security related. At times, minor + features may be introduced during a 'bugfix' release but that should + not happen often. + +It should be noted that both the Minor, and Bugfix versions follow a +'even number == stable', and 'odd number == development' scheme. Therefore, +the current version in git will always end in an 'odd number'. For example, +if the current stable version is '2.0.18', then the version in 'stable/2.0.x' +would be '2.0.19'. That said, the 'master' branch might then be '2.1.1' which +is the first version of the next minor release. Bugfixes would get applied to +both branches, however feature updates would only be applied to 'master'. +The next stable release would then be '2.2.0' and a new git branch of +'stable/2.2.x' will be created. + + + diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst index 32c56255..ea445682 100644 --- a/doc/source/dev/index.rst +++ b/doc/source/dev/index.rst @@ -23,3 +23,4 @@ them in your applications. cleanup caching testing + contributing diff --git a/doc/source/index.rst b/doc/source/index.rst index 516de9fb..7c175644 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -65,6 +65,7 @@ Documentation changes license + contributors api/index .. toctree::