Skip to content

Commit

Permalink
Merge pull request #46 from nicholasamorim/documentation_review
Browse files Browse the repository at this point in the history 
Documentation reviewed
  • Loading branch information
@DamnWidget
DamnWidget committed Dec 2, 2013
2 parents a7d5174 + 516fb29 commit bad9cea
Show file tree
Hide file tree
Showing 22 changed files with 241 additions and 234 deletions.
2 changes: 1 addition & 1 deletion docs/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,7 @@ Mamba integrates the Jinja2 templating system as a core component of the framewo
Deployment
----------

Mamba integrates the Fabric deployment library and it's used by Mamba itself to release new versions and deploy the framework to the live mamba web site. To see an example of usage you can check the `mamba devel <https://github.com/DamnWidget/mamba_devel>`_ package on GitHub.
Mamba integrates the Fabric deployment library and it's used by Mamba itself to release new versions and deploy the framework to the live mamba web site. To see an example of usage you can check the `mamba devel <https://github.com/PyMamba/mamba_devel>`_ package on GitHub.

.. autoclass:: mamba.deployment.deployer.DeployerImporter
:members:
Expand Down
4 changes: 2 additions & 2 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,13 +67,13 @@
.. _pep8: http://www.python.org/dev/peps/pep-0008/
.. |repo| replace:: GitHub repository
.. _repo: https://github.com/DamnWidget/mamba
.. _repo: https://github.com/PyMamba/mamba-framework
.. |less| replace:: LESS
.. _less: http://lesscss.org/
.. |relnotes| replace:: relnotes index
.. _relnotes: https://github.com/DamnWidget/mamba/blob/master/docs/relnotes/index.rst
.. _relnotes: https://github.com/PyMamba/mamba-framework/blob/master/docs/relnotes/index.rst
.. |noasync| replace:: This method is not asynchronous!
"""
Expand Down
10 changes: 5 additions & 5 deletions docs/contributing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,21 @@
Contributing to Mamba
=====================

There are many ways that you can contribute and get involved in the mamba project. Even if you are not a programmer, there are ways that you can help to make mamba more useful for yourself and others.
There are many ways that you can contribute and get involved in the Mamba project. Even if you are not a programmer, there are ways that you can help to make Mamba more useful for yourself and others.

The following is a list of possible ways to contribute and get involved with the mamba project.

User Feedback
-------------

In order to improve mamba, we need feedback from both users and developers with bug reports, ideas and suggestions. For that we recommend to filling a new issue in the `GitHub project issues tracker <https://github.com/DamnWidget/mamba/issues>`_ for the project.
In order to improve Mamba, we need feedback from both users and developers with bug reports, ideas and suggestions. For that we recommend to filling a new issue in the `GitHub project issues tracker <https://github.com/PyMamba/mamba-framework/issues>`_ for the project.

You can also send an email to any of the `mamba mailing lists <http://www.pymamba.com/contact`.

Documentation contributions
---------------------------

If you want to contribute with some documentation for the project, thank you very much, we really appreciate it. Mamba uses the |sphinx|_ documentation system so you should be familiarized with it if you want to contribute mamba with some documentation.
If you want to contribute with some documentation for the project, thank you very much, we really appreciate it. Mamba uses the |sphinx|_ documentation system so you should be familiarized with it if you want to contribute Mamba with some documentation.

Code contributions
------------------
Expand All @@ -27,11 +27,11 @@ Of course code contributions are more than welcome, please, take your time to re
Useful documentation for contributors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* :doc:`contributing/guide_to_code_contributions` is a basic overview about how to contribute code to the mamba project
* :doc:`contributing/guide_to_code_contributions` is a basic overview about how to contribute code to the Mamba project

Others way to contribute with mamba
-----------------------------------

As you already noticed, no mamba developers are native english speakers so corrections to the full documentation will be really welcomed.
As you may have already noticed, none of the Mamba developers are native english speakers so corrections to the full documentation will be really welcomed.

|
14 changes: 7 additions & 7 deletions docs/contributing/coding_style.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
Mamba coding style guide
========================

Like other Python projects, mamba try to follow the |pep8|_ and |sphinx|_ as docstrings conventions. Make sure to read those documents if you intent to contrbute to Mamba.
Like other Python projects, Mamba try to follow the |pep8|_ and |sphinx|_ as docstrings conventions. Make sure to read those documents if you intent to contrbute to Mamba.

Naming conventions
------------------
Expand All @@ -29,17 +29,17 @@ Style rules
Inconsistences
--------------

Mamba uses |twisted|_ as his main component and Twisted doesn't follow |pep8|_ coding style and is never going to follow it. Because that you are going to be aware of some pretty inconsistences where we use twisted objects and methods.
Mamba uses |twisted|_ as its main component and Twisted doesn't follow |pep8|_ coding style and is never going to follow it. Because of that, be aware of some inconsistences where we use twisted objects and methods.

We want to be clear on that, we **never** use |twisted| coding name conventions in exclusive mamba code, **no exceptions** to this rule.
We want to be clear on that: we **never** use |twisted| coding name conventions in exclusive Mamba code, **no exceptions** to this rule.

Principles
----------

#. Never violates `DRY <http://programmer.97things.oreilly.com/wiki/index.php/Don%27t_Repeat_Yourself>`_
#. Any code change **must** pass unit tests and shouldn't break any other test in the system
#. No commit should break the master build
#. No change should break user code silently, deprecations and incompatibilities must be always a known (and a well documented) matter
#. Never violates `DRY <http://programmer.97things.oreilly.com/wiki/index.php/Don%27t_Repeat_Yourself>`_.
#. Any code change **must** pass unit tests and shouldn't break any other test in the system.
#. No commit should break the master build.
#. No change should break user code silently, deprecations and incompatibilities must be always a known (and a well documented) matter.

|
|
4 changes: 2 additions & 2 deletions docs/contributing/guide_to_code_contributions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
Mamba guide to code contributions
=================================

This is just a basic guide to mamba development. If you came here looking for a guide about how to use mamba to develop web applications, please, refer to the :doc:`../development/mamba_development_guide`.
This is just a basic guide to Mamba development. If you came here looking for a guide about how to use Mamba to develop web applications, please, refer to the :doc:`../development/mamba_development_guide`.

Just a few considerations
-------------------------
Expand All @@ -14,7 +14,7 @@ We assume you have already a `GitHub <https://github.com>`_ account and you know

Mamba follows the workflow described in this `Git Workflow <https://sandofsky.com/blog/git-workflow.html>`_ Document wrote by Benjamin Sandofsky.

You should be familiarized already with mamba concepts. In particular you should read and understand :doc:`mamba_12_steps`, :doc:`submitting_code` and :doc:`coding_style`.
You should be familiarized already with Mamba concepts. In particular you should read and understand :doc:`mamba_12_steps`, :doc:`submitting_code` and :doc:`coding_style`.

Contributors documentation
--------------------------
Expand Down
18 changes: 9 additions & 9 deletions docs/contributing/mamba_12_steps.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,22 @@
Mamba's 12 steps workflow
=========================

This is the general process for commiting code into the master branch of mamba project. There are exceptions to this general workflow for example for security or critical bug fixes, minor changes to documentation and typo fixes or fix a broken build.
This is the general process for commiting code into the master branch of Mamba project. There are exceptions to this general workflow for example for security or critical bug fixes, minor changes to documentation and typo fixes or fix a broken build.

All the development workflow is performed in the `Mamba's GitHub <https://github.com/DamnWidget/mamba>`_ project site.
All the development workflow is performed in the `Mamba's GitHub <https://github.com/PyMamba/mamba-framework/issues>`_ project site.

#. When you are going to start to work in a fix or a feature you have to make sure of
#. Make sure there is already an open issue about the code you are going to submit. If not, create it yourself.
#. The issue has been discussed and approved by the mamba's development team
#. If the fix or feature affects the mamba core, make sure a mamba core developer is working (or is going to) with you in the integration of the code into mamba
#. You should perform your work in your own `fork <https://help.github.com/articles/fork-a-repo>`_
#. You have to do it into a new `branch <http://git-scm.com/book/en/Git-Branching-What-a-Branch-Is>`_
#. The issue has been discussed and approved by the mamba's development team.
#. If the fix or feature affects the mamba core, make sure a mamba core developer is working (or is going to) with you in the integration of the code into mamba.
#. You should perform your work in your own `fork <https://help.github.com/articles/fork-a-repo>`_.
#. You have to do it into a new `branch <http://git-scm.com/book/en/Git-Branching-What-a-Branch-Is>`_.
#. Make sure your fork is `synced <https://help.github.com/articles/syncing-a-fork>`_ with the last in-development version and your branch is `rebased <http://git-scm.com/book/en/Git-Branching-Rebasing>`_ if needed.
#. Make sure you add an entry about the new fix/feature that you introduced on mamba into the |relnotes|_ file
#. Make sure you add an entry about the new fix/feature that you introduced on Mamba into the |relnotes|_ file.
#. Make sure you add whatever documentation that is needed following the documentation for the project, thank you very much, we really appreciate it. Mamba uses the |sphinx|_ documentation syntax.
#. Make sure you reference the issue or issues that your changes affects in your `commit message <https://help.github.com/articles/closing-issues-via-commit-messages>`_ so we can just track the code from the issues panel.
#. When your work is complete you should send a `Pull Request <https://help.github.com/articles/using-pull-requests>`_ on GitHub
#. Your pull request will be then reviewed by mamba developers and other contributors.
#. Your pull request will be then reviewed by Mamba developers and other contributors.
#. If there are issues with your code in the review, you should fix them and pushing your changes for new review (make sure you add a new comment in the pull request issue thread as GitHub doesn't alert anyone about new commits added into a pull request).
#. When the review finish, a core developer will merge your contribution into the master branch
#. When the review finishes, a core developer will merge your contribution into the master branch.
#. Goto step 1
18 changes: 9 additions & 9 deletions docs/contributing/submitting_code.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@
Howto submit code
=================

Code submition in mamba is done through `GitHub pull requests system <https://help.github.com/articles/using-pull-requests>`_ so you should be familiarized with it before trying to contribute your code with mamba.
Code submition in Mamba is done through `GitHub pull requests system <https://help.github.com/articles/using-pull-requests>`_ so you should be familiarized with it before trying to contribute your code with Mamba.


Contributing with a bug fix
---------------------------

You found a bug and you want to fix it and share the fix with the rest of the community?. First of all, thank you very much, contributions like that make mamba better and maintains it alive.
You found a bug and you want to fix it and share the fix with the rest of the community?. First of all, thank you very much, contributions like that make Mamba better and maintains it alive.

Before start working in your fix, you have to go to the `mamba issues <https://github.com/DamnWidget/mamba/issues>`_ and look for the bug that you've found because maybe some other person is working on fix it already.
Before start working in your fix, you have to go to the `mamba issues <https://github.com/PyMamba/mamba-framework/issues>`_ and look for the bug that you've found because maybe some other person is working on fix it already.

If you don't find any open issue related to the bug that you found, make sure that the bug is not already fixed in a more up-to-date version of mamba. You can do that just checking the code in the last commit of the GitHub repo or just looking for a closed issue related with the bug.

Expand All @@ -24,7 +24,7 @@ Of course your bugfix **must** follow the :doc:`coding_style` and :doc:`unit_tes
My bug is listed as a closed issue
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

That means that the bug that you found is already fixed by another developer and is added already to a more up-to-date version of mamba or is fixed in the in-development version and it's waiting for the release of the new version of the framework.
That means that the bug that you found is already fixed by another developer and is added already to a more up-to-date version of Mamba or is fixed in the in-development version and it's waiting for the release of the new version of the framework.

What I can do then?
...................
Expand All @@ -35,15 +35,15 @@ You can pull the in-development version of the framework (that is always the las
My bug is listed as an open issue
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Then this is a known issue, just read the issue discussion thread to discover if someone else is already working on a fix for that, if someone is already working to fix this problem, you can just contact with him (or her) to work together in solving the issue.
Then this is a known issue, just read the issue discussion thread to discover if someone else is already working on a fix for that, if someone is already working to fix this problem, you can just contact him (or her) to work together in solving the issue.

If no other person is working in fix the issue, just write a new comment to the issue discussion thread informing that you are going to work on solve the issue actively and ask other developers about guidance or ideas.
If no other person is working on fixing the issue, just write a new comment to the issue discussion thread informing that you are going to work on solve the issue actively and ask other developers about guidance or ideas.


My bug is not listed anywhere
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Then you found an unknown mamba issue, create a new issue in the GitHub repo and tag it as **bug**, explain that you are starting to work on fix it and ask for any help or guidance if needed.
Then you found an unknown Mamba issue. Create a new issue in the GitHub repo and tag it as **bug**, explain that you are starting to work on fix it and ask for any help or guidance if needed.

Depending on the importance of the bug that you found, a mamba core developer may like to assist you or even solve himself the issue as fast as possible with your help.

Expand All @@ -58,10 +58,10 @@ New features **may or may not** been always welcome, that depends of the nature
.. note::
Remember that all the code that you submit to the project **must** include unit tests.

Licenseing the code
Licensing the code
-------------------

All the code that get into the mamba framework **must** be licensed under the **GPLv3** (or a later version on your choice) license.
All the code that get into the Mamba framework **must** be licensed under the **GPLv3** (or a later version on your choice) license.

|
|
14 changes: 7 additions & 7 deletions docs/contributing/unit_tests.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@
Unit testing
============

Each unit test will test a single functionallity of the system. Unit tests are automated and should run with no human intervention. The output of an unit test should be **pass** or **fail**. All the tests on mamba al gathered in a single test suite and can run as a single batch.
Each unit test will test a single functionallity of the system. Unit tests are automated and should run with no human intervention. The output of an unit test should be **pass** or **fail**. All the tests on mamba are gathered in a single test suite and can run as a single batch.

Howto running tests
How to run tests
-------------------

Mamba uses Twisted's `Trial <http://twistedmatrix.com/trac/wiki/TwistedTrial>`_ tool to run unit tests. To run the test suite you have to cd into the mamba root directory and run the trial tool:
Mamba uses Twisted's `Trial <http://twistedmatrix.com/trac/wiki/TwistedTrial>`_ tool to run unit tests. To run the test suite you have to cd into the Mamba root directory and run the trial tool:

$ trial mamba

Expand All @@ -21,11 +21,11 @@ You can also execute the `tests` bash script that runs `trial mamba` in the back
Adding new tests
----------------

You never add a new module to mamba without adding a batch of unit tests for the module as well. You never commit any code **until you make sure** that all the tests pass, so that means all the tests should be green when you run `trial mamba` in the root of the project.
You never add a new module to Mamba without adding a batch of unit tests for the module as well. You never commit any code **until you make sure** that all the tests pass, so that means all the tests should be green when you run `trial mamba` in the root of the project.

If you commit code that breaks the unit test suite ever you can be *hunted down* by other developers so make sure your code follow the guidelines and pass the tests.
If you commit code that breaks the unit test suite you can be *hunted down* by other developers so make sure your code follow the guidelines and pass the tests.

You have to add unit tests for your module and code because in this way other developers can check if their own changes to other parts of the code affects in any way your modules just runnign the test suite.
You have to add unit tests for your module and code because in this way other developers can check if their own changes to other parts of the code affects in any way your modules just running the test suite.

Tests go into dedicated test packages, normally `mamba/test/` for framework tests and `mamba/scripts/test` for the `mamba-admin` command line tool. Tests should be named as `test_module.py`. If the module is part of a core system like *web* you can add the tests directly into the `mamba/test/test_web.py` file.

Expand All @@ -34,7 +34,7 @@ Mamba tests cases should inherit from `twisted.trial.unittest.TestCase` instead
Twisted test implementation guidelines
--------------------------------------

The next section is exact to `twisted unit testing documentation <http://twistedmatrix.com/documents/current/core/development/policy/test-standard.html>`_, mamba is based on twisted itself so the same guidelines are applied to the implementation of unit tests. Those guidelines has been copied (and modified for convenience in some cases) as is from the current twisted version documentation.
The next section is exact to `twisted unit testing documentation <http://twistedmatrix.com/documents/current/core/development/policy/test-standard.html>`_, Mamba is based on twisted itself so the same guidelines are applied to the implementation of unit tests. Those guidelines has been copied (and modified for convenience in some cases) as is from the current twisted version documentation.

Real I/O
~~~~~~~~
Expand Down
Loading

0 comments on commit bad9cea

Please sign in to comment.