Skip to content

Contribution guidelines

Jump to bottom Edit New page
jhuet edited this page Feb 8, 2013 · 28 revisions

Other versions

Introduction

Keep in mind that dibber is in early stage of development wich makes it an application subject to a lot of changes until it reaches a more mature state.

Specifications, main ideas

The specifications of the application are not totally designed yet. As this subject requires a lot of back and forth discussions, it takes place in this mailing-list. We're not trying to make a full scope statement though, but we're rather looking into making things easy to understand by (when possible) visualy designing what we want to see in the application.

As an example there are already 2 in progress mockups of different designs (more information) :

  • version 1 with clickable links - hold shift to see them
  • version 2 without links yet - use the arrows to get thru the pages

Another way to express in an easy to understand way what could be in the application is by writing little stories about that specific thing. It would describe it in the context of being used by someone. Some generic stories about the whole application are on their way and should be available soon.

Development

The application is made using these main technologies :

Installation

The easiest way to do so is by using both git and composer. If you have none you may install them by doing : sh $ sudo apt-get install git $ curl -s http://getcomposer.org/installer | php

Then, you'll have to retrieve dibber's code and its dependencies. You may either fork this repository and then retrieve your forked code or if you just want to have a look at the code without being able to modify it you may simply do : sh $ git clone git://github.com/dibber-org/dibber.git $ cd dibber $ /path/to/composer.phar install $ chmod -R 777 data/cache data/log

Do not forget you have to have a MongoDB server running. To configure the application so it can have access to it create a file : config/autoload/module.doctrine-mongo-odm.local.php and copy the doctrine.connection part of config/autoload/module.doctrine-mongo-odm.global.php in it with the right information so it would look like this : ``` php

[ 'connection' => [ 'odm_default' => [ 'server' => 'localhost', 'port' => '27017', 'user' => 'root', 'password' => 'mybadasspwd', 'dbname' => 'dibber', 'options' => [] ], ], ], ]; ``` Pay attention to never commit your ``*.local.php`` configuration files as they are there only for your environnement. You now have a working dibber, congratz ! If you have any question have a look at the [mailing-list](https://groups.google.com/forum/#!forum/dibber) and/or ask there. #### Dev guidelines ##### Workflow As we're using git for versionning, you're asked to follow the [Git workflow](http://nvie.com/posts/a-successful-git-branching-model/). The two other important branches are : * The `master` branch is the latest stable code ready for release (ie: you never commit in it) * The `dev` branch is the latest code in development (pull requests will be merged in it) For you, this workflow basically means that if you wish to contribute by coding you have to always send a pull request (even if you have commit access). So, the steps would be : 1. Fork the project, 2. Create a branch ; depending on the nature of it prefix it with `fix/`, `feature/` or `hotfix/` followed by the issue number if any and a small description (ie : `feature/6-my-awesome-feature`), 3. Code in it, 4. Create a pull request on GitHub to the `dev` branch, 5. If needed : discuss about it in the issue comments, re-code, re-commit, 6. Then the _admin team_ will close the pull request and merge it into `dev` branch. If you need advices, help, comments, reviews... on what you're coding, do not hesitate to create a pull request and discuss about it in the issue comments. The pull request will update every time you will push to your branch. Also, i(jhuet)'m proposing to use [Trello](https://trello.com/board/development/502979250e2623863414d33e) in conjunction of the GitHub issues page as a [kanban](https://en.wikipedia.org/wiki/Kanban_(development) system. That could allow us to easily determine who's working on what and validate the different steps required for a new feature to be completed. So far i'm using [Zapier](https://zapier.com] that automatically creates a Trello card when an issue is created (even though it's pulled every 5 hours only as i'm using the free version). Nonetheless, issues discussions should always happen on GitHub. Non-issue cards can still be created manually on Trello. Discussions about them would then happen there. ##### Coding standards For now we'll borrow the coding standards used for Zend Framework 2 that you may [find here](http://framework.zend.com/wiki/display/ZFDEV2/Coding+Standards). ##### Test coverage [Atoum](https://github.com/mageekguy/atoum/) is used to make unit tests. As much as possible try to think [Test Driven Development](http://en.wikipedia.org/wiki/Test-driven_development) when you dev and provide unit tests for the pull requests you'll make. To retrieve Atoum as a dependency with composer, `cd` in the root directory of the project and : ``` sh $ /path/to/composer.phar --dev update ``` All tests are in the `/tests` directory. To run them `cd` in the root directory of the project and : ``` sh $ bin/tests.sh ``` It will run all tests and tell you wich ones pass and wich ones don't. We also highly recommand to use `assert`, `if`, `and`, `then` statements to make the tests more verbose and [easier to read](https://github.com/mageekguy/atoum/wiki/%C3%80-propos-de-if%28%29,-and%28%29,-then-et-c%C3%A6tera) (only in french for now). You way find some [examples](https://github.com/dibber-org/dibber/blob/dev/tests/Dibber/Tests/Units/Document/Place.php) in the [code](https://github.com/dibber-org/dibber/blob/dev/tests/Dibber/Tests/Units/Document/User.php) [already](https://github.com/dibber-org/dibber/blob/dev/tests/Dibber/Tests/Units/Document/Mapper/Base.php). You can find some help on [how to use atoum here](https://github.com/geraldcroes/atoum-s-documentation/blob/master/Contents/chapter1.md). ##### Continuous integration Continuous integration is done thanks to [Travis CI](http://travis-ci.org/). You can see the result of the last build and the previous ones on [this page](http://travis-ci.org/#!/dibber-org/dibber). Icons showing if the last build passed or failed for the `master` and `dev` branches are also on [the main page](https://github.com/dibber-org/dibber#readme) here on GitHub. Travis requires to have a [`.travis.yml`](https://github.com/dibber-org/dibber/blob/master/.travis.yml) file at the root of the project. It contains the scripts that it will execute in order to do the whole process. If you want to know more about its syntax, you can read the [Travis guide](http://about.travis-ci.org/docs/user/getting-started/). Only `master` and `dev` branches will be built. If you make a branch, builds will start as soon as you make your first pull request to the `dev` branch. Then every commit on that branch will update the pull request and start a new build. If you know that a commit does not need to be build, you may add ``[ci skip]`` to the commit message. ### Design / Interface Soon... ### Translation We'll certainly use [Transifex](https://www.transifex.net/) when the time comes.
Add a custom footer
Add a custom sidebar
Clone this wiki locally