Contributing to Alloy UI - New Rules and Policies
Staff Blogs August 15, 2013 By Iliyan Peychev Staff
AlloyUI is the engine which drives the UI of all Liferay products. Since it was created in 2009, it has grown really fast and we are very close to the point where we will release ver. 2.0. We will appreciate if you give us some feedback!
Over the years, tests and documentation have sometimes been sacrificed in order to speed up the development process. As result, not all of the modules had tests or documentation. When there were only two or three developers, the lack of tests wasn't such a big issue. They knew the code very well and the risk of regressions was relatively low. However, when more and more contributors were involved, this stopped working and made it harder and harder to keep the library in good condition.
As a result, we have instituted new policies related to the tests and documentation which have recently been added to AlloyUI. We would love to share them with you:
1. No single commit should go to AlloyUI source tree without tests. Exceptions are allowed for some source formatting (like renaming variables or converting spaces to tabs, etc.), but for each bugfix or for each feature added, tests must be present.
Tests in Alloy are done using YUI tests, so if you want to contribute to the library, but you are not familiar with YUI tests, you may take a look here. It is quite easy, interesting, and it does not take much time. In fact, every single minute spent on making tests will repay you and our community double. In addition to YUI tests, Yeti can be used to execute the tests on multiple browsers simultaneously.
2. All code should be properly documented. Documentation should be considered as part of the code. The guidelines for creating documentation could be found here:
3. When tests are added (especially as part of a bug fix), in the beginning of the function there must be an annotation, pointing to the corresponding ticket, published here. For example:
* Ensure all event listeners are destroyed properly.
* @tests AUI-1234
4. The changes should be described in HISTORY.md file which every module has, so it is easy to track which changes have been added between two versions. An example:
* #AUI-938 Fixed issue with TogglerDelegate collapsing direct ancestors on structures with nested togglers
* #AUI-939 Addressed missing destructors in Toggler and TogglerDelegate
In short, that is it! We would highly appreciate if you help us in the process of creating tests and documentation. There is no better way to get involved in this great project!