Repository: zeppelin Updated Branches: refs/heads/gh-pages 9c9e6bc06 -> 9647ba493
[ZEPPELIN-1346] Add contribution guidelines to the website ### What is this PR for? Recreation of #1354 This PR is bringing Contribution guidelines to the website. We also introduce a sidemenu on those pages allowing to create additional content. As an example, for the Web Application Guidelines, we added a page about "Defining Components" In a different PR, we will remove the contributing markdown, and change the links in the repository to the website. The layout of the doc was slightly modified to allow a larger documentation at max size. It was also modified to accommodate better on smaller screens. ### What type of PR is it? Documentation ### What is the Jira issue? https://issues.apache.org/jira/browse/ZEPPELIN-1346 ### How should this be tested? Build the website locally and visit the community page ### Screenshots (if appropriate) ![screen shot 2016-08-23 at 3 50 41 pm](https://cloud.githubusercontent.com/assets/710411/17882774/8da96b86-6949-11e6-8789-fed606b64fd8.png) <img width="1346" alt="screen shot 2016-08-31 at 10 33 36 am" src="https://cloud.githubusercontent.com/assets/710411/18113150/7bb2a152-6f68-11e6-8678-667c2d4f07ef.png"> #### Layout update (Before / After) Navbar Bug fix <img width="908" alt="screen shot 2016-08-31 at 10 35 14 am" src="https://cloud.githubusercontent.com/assets/710411/18113174/a374ee84-6f68-11e6-8878-a8eb7b564bd7.png"> <img width="781" alt="screen shot 2016-08-31 at 10 31 18 am" src="https://cloud.githubusercontent.com/assets/710411/18113161/9a280b0e-6f68-11e6-8dc5-1656b5bc86b1.png"> Small Device Margin Improvement <img width="402" alt="screen shot 2016-08-31 at 10 35 34 am" src="https://cloud.githubusercontent.com/assets/710411/18113176/a590f74e-6f68-11e6-8468-18274413be28.png"> <img width="398" alt="screen shot 2016-08-31 at 10 31 28 am" src="https://cloud.githubusercontent.com/assets/710411/18113168/9e904d5a-6f68-11e6-9a2e-2536cbf7a37f.png"> Content Width Change <img width="953" alt="screen shot 2016-08-31 at 10 33 50 am" src="https://cloud.githubusercontent.com/assets/710411/18113180/a7fc954c-6f68-11e6-8d58-08afb54549c1.png"> <img width="1023" alt="screen shot 2016-08-31 at 10 32 12 am" src="https://cloud.githubusercontent.com/assets/710411/18113169/a0d71aee-6f68-11e6-8654-3f124bd2a71b.png"> ### Questions: * Does the licenses files need update? No * Is there breaking changes for older versions? No * Does this needs documentation? No Author: Damien CORNEAU <cornead...@gmail.com> Author: AhyoungRyu <fbdkdu...@hanmail.net> Author: CORNEAU Damien <cornead...@gmail.com> Closes #1356 from corneadoug/add/ContributeCategory and squashes the following commits: 1a45b92 [Damien CORNEAU] Improve margin for small devices 9169c68 [Damien CORNEAU] Improve wording and spacing in contribution docs d31cf3f [Damien CORNEAU] Improve CSS for the content a469d52 [Damien CORNEAU] Extend pages_list to support multi group 79d15a3 [Damien CORNEAU] Add Contribution Guidelines to SubMenu 934afd9 [Damien CORNEAU] Change Zeppelin to Apache Zeppelin in general.md 2d62d20 [CORNEAU Damien] Merge pull request #6 from AhyoungRyu/add/ContributeCategory-ahyoung e34fc64 [Damien CORNEAU] fix typo in front-end doc a4c924b [AhyoungRyu] Remove 'menu' property e0b4c8d [Damien CORNEAU] change name of good practice file 9882670 [Damien CORNEAU] Allows contribution page without side Menu 318c4c1 [AhyoungRyu] Add section for 'For committers only' 8f69f28 [Damien CORNEAU] Add GUI integration tests CLI e7209ea [AhyoungRyu] Add docs contribution guide 94d653b [Damien CORNEAU] Fix typos 81493ab [Damien CORNEAU] Change Side Menu style 666f3ec [Damien CORNEAU] Add first Zeppelin-web best practices page 306ae06 [Damien CORNEAU] Add zeppelin-web GPG menu c933c19 [Damien CORNEAU] Add zeppelin-web contribution page 5f7e2bd [Damien CORNEAU] Add a side menu template acc68b5 [Damien CORNEAU] Add contribution Guidelines to the website cb87608 [Damien CORNEAU] Add forgotten license headers 06238fb [Damien CORNEAU] Modify the Community page Project: http://git-wip-us.apache.org/repos/asf/zeppelin/repo Commit: http://git-wip-us.apache.org/repos/asf/zeppelin/commit/9647ba49 Tree: http://git-wip-us.apache.org/repos/asf/zeppelin/tree/9647ba49 Diff: http://git-wip-us.apache.org/repos/asf/zeppelin/diff/9647ba49 Branch: refs/heads/gh-pages Commit: 9647ba493e2cc047e7ebe718f6edf2ab9abaa9d5 Parents: 9c9e6bc Author: Damien CORNEAU <cornead...@gmail.com> Authored: Wed Aug 31 10:36:33 2016 +0900 Committer: Damien CORNEAU <cornead...@gmail.com> Committed: Tue Sep 6 13:12:15 2016 +0900 ---------------------------------------------------------------------- _includes/JB/pages_list | 42 +-- _includes/sub-views/community/contribute.md | 41 +++ _includes/sub-views/community/mailinglist.md | 27 ++ _includes/themes/zeppelin/sideMenu.html | 16 ++ _layouts/sideMenu.html | 5 + _plugins/markdown_tag.rb | 23 ++ assets/themes/zeppelin/css/style.css | 114 +++++--- community.md | 20 +- contribution/contributions.md | 257 +++++++++++++++++++ contribution/documentation.md | 182 +++++++++++++ contribution/webapplication.md | 161 ++++++++++++ contribution/zeppelinweb/goodPracticeGuide01.md | 46 ++++ 12 files changed, 862 insertions(+), 72 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/_includes/JB/pages_list ---------------------------------------------------------------------- diff --git a/_includes/JB/pages_list b/_includes/JB/pages_list index 42f827a..181d90f 100644 --- a/_includes/JB/pages_list +++ b/_includes/JB/pages_list @@ -5,18 +5,18 @@ Usage: 2) include JB/pages_list example: <ul> - {% assign pages_list = site.pages %} - {% include JB/pages_list %} - </ul> - - Grouping: (optional): - assign the 'group' variable to constrain the list to only pages/posts - in the given group. Note you must define the group manually in the page/post - meta-data to use this feature. - Grouping is mainly helpful for non-post pages. - If you want to group posts, it's easier/better to tag them, then pass the tagged posts array. - i.e. site.tags.cool_tag (this returns an array of posts tagged: cool_tag) - + {% assign pages_list = site.pages %} + {% include JB/pages_list %} + </ul> + + Grouping: (optional): + assign the 'group' variable to constrain the list to only pages/posts + in the given group. Note you must define the group manually in the page/post + meta-data to use this feature. + Grouping is mainly helpful for non-post pages. + If you want to group posts, it's easier/better to tag them, then pass the tagged posts array. + i.e. site.tags.cool_tag (this returns an array of posts tagged: cool_tag) + This helper can be seen in use at: ../_layouts/default.html -->{% endcomment %} @@ -25,15 +25,17 @@ Usage: {% else %} {% for node in pages_list %} {% if node.title != null %} - {% if group == null or group == node.group %} - {% if page.url == node.url %} - <li class="active"><a href="{{ BASE_PATH }}{{node.url}}" class="active">{{node.title}}</a></li> - {% else %} - <li><a href="{{ BASE_PATH }}{{node.url}}">{{node.title}}</a></li> - {% endif %} - {% endif %} + {% for cat in node.group %} + {% if cat == group %} + {% if page.url == node.url %} + <li class="active"><a href="{{ BASE_PATH }}{{node.url}}" class="active">{{node.title}}</a></li> + {% else %} + <li><a href="{{ BASE_PATH }}{{node.url}}">{{node.title}}</a></li> + {% endif %} + {% endif %} + {% endfor %} {% endif %} {% endfor %} {% endif %} {% assign pages_list = nil %} -{% assign group = nil %} \ No newline at end of file +{% assign group = nil %} http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/_includes/sub-views/community/contribute.md ---------------------------------------------------------------------- diff --git a/_includes/sub-views/community/contribute.md b/_includes/sub-views/community/contribute.md new file mode 100644 index 0000000..c1cc837 --- /dev/null +++ b/_includes/sub-views/community/contribute.md @@ -0,0 +1,41 @@ +<!-- +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> + +## How to contribute + +There are multiple ways you can contribute to the project. +And help is always welcome! + +### Issue Tracker + +Apache Zeppelin uses JIRA as an [Issue Tracker](https://issues.apache.org/jira/browse/ZEPPELIN). +Don't hesitate to report new bugs and improvements ideas. + +#### Contribute to the source code + +We like to get code contributions through Pull Requests on our [Github Mirror](https://github.com/apache/zeppelin). + +But before starting, please read our [Contribution guidelines](/contribution/contributions.html), it will give +you important information about our review process, and pointers on how to make a good code contribution. + +You can visit our [Issue Tracker](https://issues.apache.org/jira/browse/ZEPPELIN) to find issues to resolve, +and if your are a newcomer and don't know where to get started, we have set some [beginner issues](https://issues.apache.org/jira/browse/ZEPPELIN-1245?jql=project%20%3D%20ZEPPELIN%20AND%20status%20%3D%20Open%20AND%20labels%20%3D%20beginner). + +#### Other contributions + +Not much of a coder? There are other ways to help out: + +* Documentation and website improvements are always welcome +* Helping each other by answering questions on the Mailing List +* Participating in reviewing contributions. http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/_includes/sub-views/community/mailinglist.md ---------------------------------------------------------------------- diff --git a/_includes/sub-views/community/mailinglist.md b/_includes/sub-views/community/mailinglist.md new file mode 100644 index 0000000..e604982 --- /dev/null +++ b/_includes/sub-views/community/mailinglist.md @@ -0,0 +1,27 @@ +<!-- +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> + +## Mailing list + +Get help using Apache Zeppelin or contribute to the project on our mailing lists: + +* __Users :__ [subscribe](mailto:users-subscr...@zeppelin.apache.org?subject=send this email to subscribe), [unsubscribe](mailto:users-unsubscr...@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-users/) +<br/> +for usage questions, help, and announcements. +* __Dev :__ [subscribe](mailto:dev-subscr...@zeppelin.apache.org?subject=send this email to subscribe), [unsubscribe](mailto:dev-unsubscr...@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-dev/) +<br/> +for people wanting to contribute to the project. +* __Commits :__ [subscribe](mailto:commits-subscr...@zeppelin.apache.org?subject=send this email to subscribe), [unsubscribe](mailto:commits-unsubscr...@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-commits/) +<br/> +for commit messages and patches. http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/_includes/themes/zeppelin/sideMenu.html ---------------------------------------------------------------------- diff --git a/_includes/themes/zeppelin/sideMenu.html b/_includes/themes/zeppelin/sideMenu.html new file mode 100644 index 0000000..e9acc89 --- /dev/null +++ b/_includes/themes/zeppelin/sideMenu.html @@ -0,0 +1,16 @@ +<div class="row"> + {% if page.menu %} + <div class="sideMenu col-sm-3"> + {% assign pages_list = site.pages %} + {% assign group = page.menu %} + {% include JB/pages_list %} + </div> + <div class="col-sm-9"> + {{ content }} + </div> + {% else %} + <div class="col-sm-12"> + {{ content }} + </div> + {% endif %} +</div> http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/_layouts/sideMenu.html ---------------------------------------------------------------------- diff --git a/_layouts/sideMenu.html b/_layouts/sideMenu.html new file mode 100644 index 0000000..96fc5c2 --- /dev/null +++ b/_layouts/sideMenu.html @@ -0,0 +1,5 @@ +--- +layout: default +--- +{% include JB/setup %} +{% include themes/zeppelin/sideMenu.html %} http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/_plugins/markdown_tag.rb ---------------------------------------------------------------------- diff --git a/_plugins/markdown_tag.rb b/_plugins/markdown_tag.rb new file mode 100644 index 0000000..727bf40 --- /dev/null +++ b/_plugins/markdown_tag.rb @@ -0,0 +1,23 @@ +=begin + Jekyll tag to include Markdown text from _includes directory preprocessing with Liquid. + Usage: + {% markdown <filename> %} + Dependency: + - kramdown +=end +module Jekyll + class MarkdownTag < Liquid::Tag + def initialize(tag_name, text, tokens) + super + @text = text.strip + end + require "kramdown" + def render(context) + tmpl = File.read File.join Dir.pwd, "_includes", @text + site = context.registers[:site] + tmpl = (Liquid::Template.parse tmpl).render site.site_payload + html = Kramdown::Document.new(tmpl).to_html + end + end +end +Liquid::Template.register_tag('markdown', Jekyll::MarkdownTag) http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/assets/themes/zeppelin/css/style.css ---------------------------------------------------------------------- diff --git a/assets/themes/zeppelin/css/style.css b/assets/themes/zeppelin/css/style.css index 482847b..a22a936 100644 --- a/assets/themes/zeppelin/css/style.css +++ b/assets/themes/zeppelin/css/style.css @@ -142,19 +142,6 @@ body { background: #3071a9; } -@media (max-width: 768px) { - .navbar-collapse.in { - box-shadow: 0 2px 5px 0 rgba(0, 0, 0, 0.4); - } - - .bigFingerButton { - margin-top: 12px; - display: block; - margin-right: auto; - margin-left: auto; - } -} - .bigFingerButton { margin-right: 10px; } @@ -173,6 +160,31 @@ body { outline-width: 0; } +/* SideMenu */ + +.sideMenu li { + list-style: none; + border: 1px solid #c2c2c2; + border-bottom: none; + padding: 5px 10px; +} + +.sideMenu li a { + text-decoration: none; + color: #3071a9; +} + +.sideMenu li:first-of-type { + border-top-left-radius: 3px; + border-top-right-radius: 3px; +} + +.sideMenu li:last-of-type { + border-bottom: 1px solid #c2c2c2; + border-bottom-left-radius: 3px; + border-bottom-right-radius: 3px; +} + /* CUSTOMIZE THE CAROUSEL -------------------------------------------------- */ @@ -208,15 +220,6 @@ body { margin-bottom: 0; } -@media screen and (min-width: 768px) { - .carousel-indicators { - margin-bottom: -60px; - } - .carousel-caption { - padding-bottom: 60px; - } -} - /* screenshot img inside of doc */ .screenshot { width: 800px; @@ -235,29 +238,14 @@ body { /* Custom container */ .content { word-wrap: break-word; + max-width: 1024px; + padding: 2rem 2rem; + margin: 0 auto; } .content :first-child { margin-top: 0; } -@media screen and (min-width: 64em) { - .content { - max-width: 64em; - padding: 2rem 6rem; - margin: 0 auto; - } -} -@media screen and (min-width: 42em) and (max-width: 64em) { - .content { - padding: 2rem 4rem; - } -} -@media screen and (max-width: 42em) { - .content { - padding: 2rem 1rem; - } -} - /* <a> */ .content a { color: #4183C4; @@ -588,3 +576,49 @@ and (max-width: 1024px) { padding: 3px 10px 10px 10px; font-size: 13px; } + +/* +** Media Queries CSS +*/ + + + +@media (max-width: 991px) { + .navbar-inverse .navbar-brand { + font-size: 28px; + } + + .content { + padding: 2rem 4rem; + } +} + +@media (max-width: 768px) { + .navbar-collapse.in { + box-shadow: 0 2px 5px 0 rgba(0, 0, 0, 0.4); + } + + .bigFingerButton { + margin-top: 12px; + display: block; + margin-right: auto; + margin-left: auto; + } + + .sideMenu { + margin-bottom: 15px; + } + + .content { + padding: 2rem 2rem; + } +} + +@media screen and (min-width: 768px) { + .carousel-indicators { + margin-bottom: -60px; + } + .carousel-caption { + padding-bottom: 60px; + } +} http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/community.md ---------------------------------------------------------------------- diff --git a/community.md b/community.md index 0d30a08..79cc8a6 100644 --- a/community.md +++ b/community.md @@ -19,15 +19,11 @@ limitations under the License. --> {% include JB/setup %} - -### Mailing list - -Get help using Apache Zeppelin or contribute to the project on our mailing lists: - -* [us...@zeppelin.apache.org](http://mail-archives.apache.org/mod_mbox/zeppelin-users/) is for usage questions, help, and announcements. [subscribe](mailto:users-subscr...@zeppelin.apache.org?subject=send this email to subscribe), [unsubscribe](mailto:users-unsubscr...@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-users/) -* [d...@zeppelin.apache.org](http://mail-archives.apache.org/mod_mbox/zeppelin-dev/) is for people who want to contribute code to Zeppelin. [subscribe](mailto:dev-subscr...@zeppelin.apache.org?subject=send this email to subscribe), [unsubscribe](mailto:dev-unsubscr...@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-dev/) -* [commits@zeppelin.apache.org](http://mail-archives.apache.org/mod_mbox/zeppelin-commits/) is for commit messages and patches to Zeppelin. [subscribe](mailto:commits-subscr...@zeppelin.apache.org?subject=send this email to subscribe), [unsubscribe](mailto:commits-unsubscr...@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-commits/) - -### Issue tracker - - [https://issues.apache.org/jira/browse/ZEPPELIN](https://issues.apache.org/jira/browse/ZEPPELIN) +<div class="row"> + <div class="col-md-6"> + {% markdown sub-views/community/contribute.md %} + </div> + <div class="col-md-6"> + {% markdown sub-views/community/mailinglist.md %} + </div> +</div> http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/contribution/contributions.md ---------------------------------------------------------------------- diff --git a/contribution/contributions.md b/contribution/contributions.md new file mode 100644 index 0000000..49627df --- /dev/null +++ b/contribution/contributions.md @@ -0,0 +1,257 @@ +--- +layout: sideMenu +title: "Contributions" +description: "" +menu: nav-contrib +group: nav-contrib +--- +<!-- +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> + +# Contribution Guidelines + +**Apache Zeppelin** is an [Apache2 License](https://github.com/apache/zeppelin/blob/master/CONTRIBUTING.md) Software. + +Contributing to Zeppelin (Source code, Documents, Image, Website) means you agree to the Apache2 License. + +1. Make sure your issue is not already in the [Jira issue tracker](https://issues.apache.org/jira/browse/ZEPPELIN) +2. If not, create a ticket describing the change you're proposing in the [Jira issue tracker](https://issues.apache.org/jira/browse/ZEPPELIN) +3. Contribute your patch via Pull Request on our [Github Mirror](https://github.com/apache/zeppelin). + +Before you start, please read the [Code of Conduct](http://www.apache.org/foundation/policies/conduct.html) carefully, familiarize yourself with it and refer to it whenever you need it. + +For those of you who are not familiar with Apache project, understanding [How it works](http://www.apache.org/foundation/how-it-works.html) would be quite helpful. + +## Creating a Pull Request +When creating a Pull Request, you will automatically get the template below. + +Filling it thoroughly can improve the speed of the review process. + + ### What is this PR for? + A few sentences describing the overall goals of the pull request's commits. + First time? Check out the contribution guidelines - https://zeppelin.apache.org/contribute.html + + ### What type of PR is it? + [Bug Fix | Improvement | Feature | Documentation | Hot Fix | Refactoring] + + ### Todos + * [ ] - Task + + ### What is the Jira issue? + * Open an issue on Jira https://issues.apache.org/jira/browse/ZEPPELIN/ + * Put link here, and add [ZEPPELIN-*Jira number*] in PR title, eg. [ZEPPELIN-533] + + ### How should this be tested? + Outline the steps to test the PR here. + + ### Screenshots (if appropriate) + + ### Questions: + * Does the licenses files need update? + * Is there breaking changes for older versions? + * Does this needs documentation? + +## Testing a Pull Request +You can also test and review a particular Pull Request. Here are two useful ways. + +* Using a utility provided from Zeppelin. + + ``` + dev/test_zeppelin_pr.py [# of PR] + ``` + + For example, if you want to test `#513`, then the command will be: + + ``` + dev/test_zeppelin_pr.py 513 + ``` + +* Another way is using [github/hub](https://github.com/github/hub). + + ``` + hub checkout https://github.com/apache/zeppelin/pull/[# of PR] + ``` + +The above two methods will help you test and review Pull Requests. + +## Source Control Workflow +Zeppelin follows [Fork & Pull] (https://github.com/sevntu-checkstyle/sevntu.checkstyle/wiki/Development-workflow-with-Git:-Fork,-Branching,-Commits,-and-Pull-Request) model. + +## The Review Process + +When a Pull Request is submitted, it is being merged or rejected by the following review process. + +* Anybody can be a reviewer and may comment on the change or suggest modifications. +* Reviewer can indicate that a patch looks suitable for merging with a comment such as: "Looks good", "LGTM", "+1". +* At least one indication of suitability (e.g. "LGTM") from a committer is required to be merged. +* Pull request is open for 1 or 2 days for potential additional review, unless it's got enough indication of suitability. +* A committer can then initiate lazy consensus ("Merge if there is no more discussion") after what the code can be merged after a certain time (normally 24 hours) if there is no more reviews. +* Contributors can ping reviewers (including committers) by commenting 'Ready to review' or suitable indication. + +## Becoming a Committer + +The PMC adds new committers from the active contributors, based on their contribution to Zeppelin. + +The qualifications for new committers include: + +1. Sustained contributions: Committers should have a history of constant contributions to Zeppelin. +2. Quality of contributions: Committers more than any other community member should submit simple, well-tested, and well-designed patches. +3. Community involvement: Committers should have a constructive and friendly attitude in all community interactions. They should also be active on the dev, user list and reviewing patches. Also help new contributors and users. + + +## Setting up +Here are some things you will need to build and test Zeppelin. + +### Software Configuration Management (SCM) + +Zeppelin uses Git for its SCM system. so you'll need git client installed in your development machine. + +### Integrated Development Environment (IDE) + +You are free to use whatever IDE you prefer, or your favorite command line editor. + +### Project Structure + +Zeppelin project is based on Maven. Maven works by convention & defines [directory structure] (https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html) for a project. +The top-level pom.xml describes the basic project structure. Currently Zeppelin has the following modules. + + <module>zeppelin-interpreter</module> + <module>zeppelin-zengine</module> + <module>spark</module> + <module>markdown</module> + <module>angular</module> + <module>shell</module> + <module>flink</module> + <module>ignite</module> + <module>lens</module> + <module>cassandra</module> + <module>zeppelin-web</module> + <module>zeppelin-server</module> + <module>zeppelin-distribution</module> + +### Code convention +We are following Google Code style: + +* [Java style](https://google.github.io/styleguide/javaguide.html) +* [Shell style](https://google.github.io/styleguide/shell.xml) + +Check style report location are in `${submodule}/target/site/checkstyle.html` +Test coverage report location are in `${submodule}/target/site/cobertura/index.html` + +## Getting the source code +First of all, you need the Zeppelin source code. + +The official location for Zeppelin is [http://git.apache.org/zeppelin.git](http://git.apache.org/zeppelin.git). + +### git access + +Get the source code on your development machine using git. + +``` +git clone git://git.apache.org/zeppelin.git zeppelin +``` + +You may also want to develop against a specific branch. For example, for branch-0.5.6 + +``` +git clone -b branch-0.5.6 git://git.apache.org/zeppelin.git zeppelin +``` + +or with write access + +``` +git clone https://git-wip-us.apache.org/repos/asf/zeppelin.git +``` + +### Fork repository + +If you want not only build Zeppelin but also make change, then you need fork [Zeppelin github mirror repository](https://github.com/apache/zeppelin) and make a pull request. + + +## Build + +### Build Tools + +To build the code, install + + * Oracle Java 7 + * Apache Maven + +### Building the code + +``` +mvn install +``` + +To skip test + +``` +mvn install -DskipTests +``` + +To build with specific spark / hadoop version + +``` +mvn install -Phadoop-2.2 -Dhadoop.version=2.2.0 -Pspark-1.3 -Dspark.version=1.3.0 +``` + +## Tests +Each new File should have its own accompanying unit tests. Each new interpreter should have come with its tests. + + +Zeppelin has 3 types of tests: + +* __Unit Tests:__ The unit tests run as part of each package's build. E.g. SparkInterpeter Module's unit test is SparkInterpreterTest +* __Integration Tests:__ The integration tests run after all modules are build. The integration tests launch an instance of Zeppelin server. ZeppelinRestApiTest is an example integration test. +* __GUI integration tests:__ These tests validate the Zeppelin UI elements. These tests require a running Zeppelin server and launches a web browser to validate Notebook UI elements like Notes and their execution. See ZeppelinIT as an example. + +Currently the __GUI integration tests__ are not run in the Maven and are only run in the CI environment when the pull request is submitted to github. + +Make sure to watch the [CI results] (https://travis-ci.org/apache/zeppelin/pull_requests) for your pull request. + +#### Running GUI integration tests locally + +##### All tests, just like the CI: + +``` +PATH=~/Applications/Firefox.app/Contents/MacOS/:$PATH CI="true" mvn verify -Pspark-1.6 -Phadoop-2.3 -Ppyspark -B -pl "zeppelin-interpreter,zeppelin-zengine,zeppelin-server,zeppelin-display,spark-dependencies,spark" -Dtest="org.apache.zeppelin.AbstractFunctionalSuite" -DfailIfNoTests=false +``` + +##### Next to a Running instance of Zeppelin + +This allows you to target a specific __GUI integration test__. + +``` +TEST_SELENIUM="true" mvn package -DfailIfNoTests=false -pl 'zeppelin-interpreter,zeppelin-zengine,zeppelin-server' -Dtest=ParagraphActionsIT +``` + +## Continuous Integration + +Zeppelin uses Travis for CI. In the project root there is .travis.yml that configures CI and [publishes CI results] (https://travis-ci.org/apache/zeppelin/builds) + + +## Run Zeppelin server in development mode + +``` +cd zeppelin-server +HADOOP_HOME=YOUR_HADOOP_HOME JAVA_HOME=YOUR_JAVA_HOME mvn exec:java -Dexec.mainClass="org.apache.zeppelin.server.ZeppelinServer" -Dexec.args="" +``` + +or use daemon script + +``` +bin/zeppelin-daemon start +``` + +Server will be run on http://localhost:8080 http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/contribution/documentation.md ---------------------------------------------------------------------- diff --git a/contribution/documentation.md b/contribution/documentation.md new file mode 100644 index 0000000..0b9ec5b --- /dev/null +++ b/contribution/documentation.md @@ -0,0 +1,182 @@ +--- +layout: sideMenu +title: "Documentation" +description: "" +menu: nav-contrib +group: nav-contrib +--- +<!-- +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> + +# Contributing to Documentation + +## Dev Mode +Apache Zeppelin is using [Jekyll](https://jekyllrb.com/) which is a static site generator and [Github Pages](https://pages.github.com/) as a site publisher. + +For the more details, see [help.github.com/articles/about-github-pages-and-jekyll/](https://help.github.com/articles/about-github-pages-and-jekyll/). + +### Requirements + +``` +# ruby --version >= 2.0.0 +# Install Bundler using gem +gem install bundler + +cd $ZEPPELIN_HOME/docs +# Install all dependencies declared in the Gemfile +bundle install +``` + +For the further information about requirements, please see [here](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/#requirements). + +On OS X 10.9, you may need to do + +``` +xcode-select --install + +``` +### Run the website locally + +If you don't want to encounter uglily rendered pages, run the documentation site in your local first. + +In `$ZEPPELIN_HOME/docs` folder, run + +``` +bundle exec jekyll serve --watch +``` + +Using the above command, Jekyll will start a web server at `http://localhost:4000` and watch the `/docs` directory to update. + + +## Folder Structure & Components +`docs/` folder is organized like below: + +``` +docs/ + âââ _includes/themes/zeppelin + â âââ _navigation.html + â âââ default.html + âââ _layouts + âââ _plugins + âââ assets/themes/zeppelin -> {ASSET_PATH} + â âââ bootstrap + â âââ css + â âââ img + â âââ js + âââ development/ *.md + âââ displaysystem/ *.md + âââ install/ *.md + âââ interpreter/ *.md + âââ manual/ *.md + âââ quickstart/ *.md + âââ rest-api/ *.md + âââ security/ *.md + âââ storage/ *.md + âââ Gemfile + âââ Gemfile.lock + âââ _config.yml + âââ index.md + âââ ... +``` + + - `_navigation.html`: the dropdown menu in navbar + - `default.html` & `_layouts/`: define default HTML layout + - `_plugins/`: custom plugin `*.rb` files can be placed in this folder. See [jekyll/plugins](https://jekyllrb.com/docs/plugins/) for the further information. + - `{ASSET_PATH}/css/style.css`: extra css components can be defined + - `{ASSET_PATH}/img/docs-img/`: image files used for document pages can be placed in this folder + - `{ASSET_PATH}/js/`: extra `.js` files can be placed + - `Gemfile`: defines bundle dependencies. They will be installed by `bundle install`. + - `Gemfile.lock`: when you run `bundle install`, bundler will persist all gems name and their version to this file. For the more details, see [Bundle "The Gemfile Lock"](http://bundler.io/v1.10/man/bundle-install.1.html#THE-GEMFILE-LOCK) + - `documentation_group`: `development/`, `displaysystem/`, `install/`, `interpreter/`... + - `_config.yml`: defines configuration options for docs website. See [jekyll/configuration](https://jekyllrb.com/docs/configuration/) for the other available config variables. + - `index.md`: the main page of `http://zeppelin.apache.org/docs/<ZEPPELIN_VERSION>/` + + +### Markdown +Zeppelin documentation pages are written with [Markdown](http://daringfireball.net/projects/markdown/). It is possible to use [GitHub flavored syntax](https://help.github.com/categories/writing-on-github/) and intermix plain HTML. + +### Front matter +Every page contains [YAML front matter](https://jekyllrb.com/docs/frontmatter/) block in their header. Don't forget to wrap the front matter list with triple-dashed lines(`---`) like below. +The document page should start this triple-dashed lines. Or you will face 404 error, since Jekyll can't find the page. + +``` +--- +layout: page +title: "Apache Zeppelin Tutorial" +description: "This tutorial page contains a short walk-through tutorial that uses Apache Spark backend. Please note that this tutorial is valid for Spark 1.3 and higher." +group: quickstart +--- +``` + + - `layout`: the default layout is `page` which is defined in `_layout/page.html`. + - `title`: the title for the document. Please note that if it needs to include `Zeppelin`, it should be `Apache Zeppelin`, not `Zeppelin`. + - `description`: a short description for the document. One or two sentences would be enough. This description also will be shown as an extract sentence when people search pages. + - `group`: a category for the document page, more than on group can be applied by using this syntax: + + ``` + group: + - group1 + - group2 + ``` + +### Headings +All documents are structured with headings. From these headings, you can automatically generate a **Table of Contents**. There is a simple rule for Zeppelin docs headings. + +``` +# Level-1 heading <- used only for the main title +## Level-2 heading <- start with this +### Level-3 heading +#### Level-4 heading <- won't be converted in TOC from this level +``` + +### Table of contents (TOC) + +``` +<div id="toc"></div> +``` + +Add this line below `# main title` in order to generate a **Table of Contents**. + +Headings until `### (Level-3 heading)` are included to TOC. + + +Default setting options for TOC are definded in [here](https://github.com/apache/zeppelin/blob/master/docs/assets/themes/zeppelin/js/toc.js#L4). + + +### Adding new pages +If you're going to create new pages, there are some spots you need to add the location of the page. + + - **Dropdown menu in navbar**: add your docs location to [_navigation.html](https://github.com/apache/zeppelin/blob/master/docs/_includes/themes/zeppelin/_navigation.html) + - **Main index**: add your docs below [What is the next?](http://zeppelin.apache.org/docs/latest/#what-is-the-next) section in [index.md](https://github.com/apache/zeppelin/blob/master/docs/index.md) with a short description. No need to do this if the page is for **Interpreters**. + + +## For committers only +### Bumping up version in a new release + +`ZEPPELIN_VERSION` and `BASE_PATH` property in `_config.yml` + +### Deploy to ASF svnpubsub infra + 1. generate static website in `./_site` + + ``` + # go to /docs under Zeppelin source + bundle exec jekyll build --safe + ``` + + 2. checkout ASF repo + ``` + svn co https://svn.apache.org/repos/asf/zeppelin asf-zeppelin + ``` + 3. copy `zeppelin/docs/_site` to `asf-zeppelin/site/docs/[VERSION]` + 4. ```svn commit``` http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/contribution/webapplication.md ---------------------------------------------------------------------- diff --git a/contribution/webapplication.md b/contribution/webapplication.md new file mode 100644 index 0000000..8010e10 --- /dev/null +++ b/contribution/webapplication.md @@ -0,0 +1,161 @@ +--- +layout: sideMenu +title: "Web Application" +description: "" +group: +- nav-contrib +- nav-contrib-front +menu: nav-contrib-front +--- +<!-- +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> + +# Contributing to Zeppelin-Web + +## Dev Mode +When working on Zeppelin's WebApplication, it is recommended to run in dev mode. + +For that, start Zeppelin server normally, then use ``./grunt serve`` in _zeppelin-web_ directory. + +This will launch a Zeppelin WebApplication on port **9000** that will update on code changes. + +## Technologies + +Zeppelin WebApplication is using **AngularJS** as main Framework, and **Grunt** and **Bower** as helpers. + +So you might want to get familiar with it. +[Here is a good start](http://www.sitepoint.com/kickstart-your-angularjs-development-with-yeoman-grunt-and-bower/) +(There is obviously plenty more ressources to learn) + +## Good Practices + +On the side menu of this page, you will find documentation about some of the best practices we want to apply +in this project. + +This is a great way for people to learn more about angularJS, and to keep the code clean and optimized. + +Please try to follow those __Good Practices Guides__ when making a PR or reviewing one. + +## Coding style + +* We follow mainly the [Google Javascript Guide](https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml) +* We use a 2 spaces indentation +* We use single quotes + +But don't worry, Eslint and Jscs will make you remember it for the most part. + +We try not to have **JQuery except in directives**, If you want to include a library, +please search for its **angularJS** directive first. + +If you still need to use it, then please use ``angular.element()`` instead of ``$()`` + +## Folder Structure & Code Organization + +* `src` folder: Contains the Source code for Zeppelin WebApplication +* `dist` folder: Contains the compiled code after using **grunt build** + +### Src and Code Organization + +The `src` folder is organized as such: + +<pre> + src/ + âââ app/ + â âââ name/ + â â âââ name.controller.js + | | âââ name.html + | | âââ subComponent1/ + | | | âââ subComponent1.html + | | | âââ subComponent1.css + â | | âââ subComponent1.controller.js + â â âââ name.css + â âââ app.js + âââ assets/ + â âââ images/ + â âââ styles/ + | âââ looknfeel/ + â âââ printMode.css + âââ components/ + â âââ component1/ + | | âââ component1.html + â | âââ component1.controller.js + â âââ component2/ + âââ fonts/ + | âââ *.{eot,svg,ttf,woff,otf} + â âââ *.css + âââ favico.ico + âââ index.html + âââ 404.html +</pre> + +The code is now organized in a component type of architecture, where everything is logically grouped. + +#### File type name convention + +In order to understand what is contained inside the .js files without opening it, we use some name conventions: + +* .controller.js +* .directive.js +* .service.js + +### Component Architecture + +When we talk about Component architecture, we think about grouping files together in a logical way. + +A component can then be made of multiple files like `.html`, `.css` or any other file type mentioned above. + +Related components can be grouped as sub-component as long as they are used in that component only. + + +#### App folder + +Contains the application `app.js` and page related components. + +* Home Page +* Interpreter Page +* Notebook Page +etc... + +The only resctiction being that a component in the `app` folder is **not used anywhere else** + +#### Components folder + +The `components` folder is here to contains any reusable component (used more than once) + +### Fonts + +Fonts files and their css are mixed together in the `fonts` folder + +## New files includes + +As we do not use yeoman to generate controllers or other type of files with this new structure, +we need to do some includes manually in `index.html` in order to use dev mode and compile correctly. + +* Non-bower `.js` files needs to be injected between the tag `<!-- build:js({.tmp,src}) scripts/scripts.js -->` +* Css files needs to be injected between the tag `<!-- build:css(.tmp) styles/main.css -->` + +## Add plugins with Bower +``` +bower install <plugin> --save +``` +The file index.html will automatically update with the new bower_component + +<br/> + +**Example**: `./bower install angular-nvd3` + +You should find that line in the index.html file +``` +<script src="bower_components/angular-nvd3/dist/angular-nvd3.js"></script> +```` http://git-wip-us.apache.org/repos/asf/zeppelin/blob/9647ba49/contribution/zeppelinweb/goodPracticeGuide01.md ---------------------------------------------------------------------- diff --git a/contribution/zeppelinweb/goodPracticeGuide01.md b/contribution/zeppelinweb/goodPracticeGuide01.md new file mode 100644 index 0000000..7580b77 --- /dev/null +++ b/contribution/zeppelinweb/goodPracticeGuide01.md @@ -0,0 +1,46 @@ +--- +layout: sideMenu +title: "Defining Components" +description: "" +group: nav-contrib-front +menu: nav-contrib-front +--- +<!-- +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> + +# Defining Angular Components + +<br/> +We should have only one Angular Component per file, and it should look like this: + +``` +(function() { + 'use strict'; + + angular.module('zeppelinWebApp').controller('HomeCtrl', HomeCtrl); + + HomeCtrl.$inject = ['$location']; + + function HomeCtrl($location) { + ... + } + +})(); +``` + +#### Explanations + +* The component function and the component's dependency injection are separated from the component definition +* We apply an Immediately Invoked Function Expression (IIFE) to each component, You can learn more about it +in this [nice post](https://github.com/johnpapa/angular-styleguide/tree/master/a1#iife) of John Papa.