|
| 1 | +# Contributing |
| 2 | + |
| 3 | +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 was not a big issue since they knew the code very well and the risk of regressions was relatively low, however, when more and more [contributors](http://alloyui.com/about/) were involved, this stopped working and made it harder and harder to keep the library in good condition. |
| 4 | + |
| 5 | +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: |
| 6 | + |
| 7 | +## 1. Issues |
| 8 | + |
| 9 | +First of all, you should know that we are not using [GitHub Issues](https://github.com/liferay/alloy-ui/issues), instead we use [Jira](http://issues.liferay.com/browse/AUI). |
| 10 | + |
| 11 | +In order for us to help you, please check that you have completed the following steps: |
| 12 | + |
| 13 | +* Make sure that you are using the latest version. |
| 14 | +* Look through the list of issues to ensure that the bug has not already been reported. |
| 15 | + |
| 16 | +If you are still facing the problem, go ahead and [create an issue](http://issues.liferay.com/secure/CreateIssue!default.jspa). Just remember to include as much information about the bug as possible. |
| 17 | + |
| 18 | +## 2. Code Style |
| 19 | + |
| 20 | +This project uses single-quotes, four space indentation and white space around arguments. Please ensure any pull requests follow this closely by using the [EditorConfig file](https://github.com/liferay/alloyui.com/blob/master/.editorconfig) and linting your code with our [JSHint options](https://github.com/liferay/alloyui.com/blob/master/.jshintrc). If you notice existing code which does not follow these practices, feel free to shout out and we will change it. |
| 21 | + |
| 22 | +> See [AlloyUI Code Style Guidelines](https://github.com/liferay/alloy-ui/wiki/Code-Style-Guidelines). |
| 23 | +
|
| 24 | +## 3. Tests |
| 25 | + |
| 26 | +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 bug fix or for each feature added, **tests must be present**. |
| 27 | + |
| 28 | +> See [AlloyUI Testing Guidelines](https://github.com/liferay/alloy-ui/wiki/Testing-Guidelines). |
| 29 | +
|
| 30 | +## 4. Documentation |
| 31 | + |
| 32 | +All code should be properly documented using [YUIDoc syntax](http://yui.github.io/yuidoc/syntax/index.html). Documentation should be considered as part of the code. |
| 33 | + |
| 34 | +> See [AlloyUI Documentation Guidelines](https://github.com/liferay/alloy-ui/wiki/Documentation-Guidelines). |
| 35 | +
|
| 36 | +## 5. History |
| 37 | + |
| 38 | +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. |
| 39 | + |
| 40 | +## Conclusion |
| 41 | + |
| 42 | +In short, that is it! |
| 43 | + |
| 44 | +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! |
| 45 | + |
| 46 | +Happy hacking! |
| 47 | + |
| 48 | +## Setup |
| 49 | + |
| 50 | +1. Install NodeJS <= [v0.12.0](http://nodejs.org/dist/v0.12.0/), if you do not have it yet. |
| 51 | + |
| 52 | +2. Install global dependencies: |
| 53 | + |
| 54 | +``` |
| 55 | +[sudo] npm install -g gulp |
| 56 | +``` |
| 57 | + |
| 58 | +3. Install local dependencies: |
| 59 | + |
| 60 | +``` |
| 61 | +npm install |
| 62 | +``` |
| 63 | + |
| 64 | +4. Initialize and fetch dependencies via Bower: |
| 65 | + |
| 66 | +``` |
| 67 | +gulp init |
| 68 | +``` |
| 69 | + |
| 70 | +5. Build AlloyUI & YUI3 using Shifter: |
| 71 | + |
| 72 | +``` |
| 73 | +gulp build |
| 74 | +``` |
| 75 | + |
| 76 | +## Development |
| 77 | + |
| 78 | +Rebuild AUI components: |
| 79 | + |
| 80 | +``` |
| 81 | +gulp build-aui |
| 82 | +``` |
| 83 | + |
| 84 | +If run at the root level, it will build all AUI components. |
| 85 | + |
| 86 | +If run within a component folder (ie. `cd src/aui-datatable`), it will only build that specific component. |
| 87 | + |
| 88 | +Watch for changes and rebuild automatically: |
| 89 | + |
| 90 | +``` |
| 91 | +gulp watch |
| 92 | +``` |
| 93 | + |
| 94 | +### Testing your local version of Alloy UI |
| 95 | + |
| 96 | +When developing, it is good practice to test the changes you make in various environments. |
| 97 | + |
| 98 | +Since Alloy UI is used primarily within [Liferay portal](https://github.com/liferay/liferay-portal), it is important to have your changes tested in Liferay to ensure there are no regressions. |
| 99 | + |
| 100 | +We have created the `liferay-gulp-tasks` package to help deploying a local version to test. |
| 101 | + |
| 102 | +Once you have made all your necessary modifications and built a working copy of Alloy UI and are ready for testing, you can run: |
| 103 | + |
| 104 | +``` |
| 105 | +gulp maven-install |
| 106 | +``` |
| 107 | + |
| 108 | +This command will put a local AlloyUI version in you `~/.m2` folder which is where Liferay will search for local WebJars. If they are not found locally, Liferay will search of them on Nexus, and if found, it will download it to be consumed by Liferay. |
| 109 | + |
| 110 | +When you have successfully run the command to put this local version on your machine, you will need to update the `build.gradle` files in Liferay to use these new versions of Alloy UI. |
| 111 | + |
| 112 | +You will need to update `String alloyUIVersion = [VERSION]` found at [https://github.com/liferay/liferay-portal/blob/master/modules/apps/frontend-js/frontend-js-aui-web/build.gradle#L10](https://github.com/liferay/liferay-portal/blob/master/modules/apps/frontend-js/frontend-js-aui-web/build.gradle#L10) and [https://github.com/liferay/liferay-portal/blob/master/modules/apps/frontend-theme/frontend-theme-unstyled/build.gradle#L18](https://github.com/liferay/liferay-portal/blob/master/modules/apps/frontend-theme/frontend-theme-unstyled/build.gradle#L18) to this new version. |
| 113 | + |
| 114 | +When completed, you can redeploy the 2 Liferay modules, `frontend-js` and `frontend-theme` to test your changes. |
0 commit comments