From 4e4133cee79bbc3620b95da1856d6379e8f594e8 Mon Sep 17 00:00:00 2001 From: Michael Neale Date: Thu, 26 May 2016 13:51:46 +1000 Subject: [PATCH] big cleanup of dev docs (#203) * big cleanup of dev docs * fixes for README --- README.md | 80 +++++++++++++++++++++++++---------- blueocean-dashboard/README.md | 5 ++- blueocean-plugin/README.md | 44 +++++++++++++++++-- blueocean-rest/README.md | 12 ++++-- blueocean-web/README.md | 59 +++++--------------------- 5 files changed, 119 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index a5ad73d0..5c8672a3 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,41 @@ -This is the BlueOcean repo. It is a multi-module maven project. Each sub-directory at the root of the repo is jenkins extension. +Blue Ocean is the next generation user experience for Jenkins. + +It is a multi-module maven project with a few Jenkins plugins. + +Read it: +https://jenkins.io//blog/2016/05/26/introducing-blue-ocean/ -Blue Ocean is the new UI project for Jenkins. ![Pirate logo, because it's ocean and stuff](logo-yarrr.png) Yarr... # Modules of note -(check the readme in each of them!) - -## blueocean-web - -BlueOcean Web module, core web module with layout and extention points. You probably want to look at the README for this for how to play with it. This should mostly be infrastructure and core components. - ## blueocean-dashboard -BlueOcean Dashboard plugin. Currently contains the bulk of the Blue Ocean user interface. - -## blueocean-commons - -Common libraries for various modules - -## blueocean-rest - -Utilities and interfaces for the HTTP api that the Blue Ocean front end needs. +Blue Ocean Dashboard plugin. Currently contains the bulk of the Blue Ocean user interface. This is mostly client side JavaScript built with ES6 and React. ## blueocean-plugin -This plugin currently fulfills two purposes (and so is likely to be separated out into two plugins - TBD): +This plugin currently exists for two purposes (and so is likely to be separated out into two plugins - TBD): 1. Provides the default implementation of the REST Api defined in the `blueocean-rest` plugin. -1. Acts as an aggregator plugin, making it an easy place from which to run Blue Ocean via `hpi:run`. +2. Acts as an aggregator plugin, making it an easy place from which to run Blue Ocean via `hpi:run`. __NOTE__: As already stated, this plugin is likely to be refactored in the near future. + + +## blueocean-rest + +Java interfaces and classes that specify the definition of the REST API. See the README within this module for more information. + +## blueocean-web + +Web infrastructure that glues Jenkins and Blue Ocean plugin together on the /blue endpoint. + -# Building +# Building and running ## Build everything (from root directory) Builds all maven modules (run this the first time you check things out, at least) @@ -44,9 +44,35 @@ Builds all maven modules (run this the first time you check things out, at least $ mvn clean install ``` -# Running Blue Ocean +## Running Blue Ocean + +``` +$ cd blueocean-plugin +$ mvn hpi:run +``` + +Then open http://localhost:8080/jenkins/blue to start using Blue Ocean. + +The Jenkins Classic UI exists side-by-side at its usual place at http://localhost:8080/jenkins. + +# Developing + +Follow the steps above for getting it running first. + +Look in following README's for: +* ``blueocean-dashboard`` guide on how to modify the GUI in the dashboard plugin. https://github.com/cloudbees/blueocean-sample-pipeline-result-ext-plugin has a video/sample of a plugin that extends Blue Ocean. +* ``blueocean-rest`` for how to navigate the rest api. +* ``blueocean-plugin`` for more details on how to actively develop this plugin for both the frontend and backend codebases. + +### Tools needed + +*Maven* is used for most building. The project is configured to grab all the tools you need from the JavaScript ecosystem to get started. + +If you are working on the Javascript, you will need node and gulp installed. + + +__NOTE__: look in the README.md of the respective modules for more detailed dev docs. -Go into blueocean-web and follow the README.md! # Debug and live reload with IntelliJ @@ -61,3 +87,13 @@ Automatically deploys changes to an instance of blueocean that is run with hpi:r * Runner > Properties: Enable Skip tests * Runner > VM Options: `-Dblueocean.config.file=../app.properties` 3. Debug new configuration, and after compilation the class file will be reloaded + +# Help + +Need help? + +You can chat to folks on #jenkins-ux on freenode (IRC). You can also email the jenkins-dev email list (google group: https://groups.google.com/forum/#!forum/jenkinsci-dev) - but ensure you use the prefix [Blue Ocean] in your subject line when posting. + +# Presentations + +Advanced front end development with react, redux and stuff by @scherler: https://docs.google.com/presentation/d/1dbaYTIGjGT9xX1JnWnaqjMumq94M9nGwljfMQaVtUFc/edit?usp=sharing diff --git a/blueocean-dashboard/README.md b/blueocean-dashboard/README.md index aab1e391..03ccae58 100644 --- a/blueocean-dashboard/README.md +++ b/blueocean-dashboard/README.md @@ -1,12 +1,13 @@ # Dashboard plugin This plugin provides the main Dashboard user interface for Blue Ocean. +It has a bunch of GUI components and extension points for other plugins to extend. +This is where the fun happens. -## Running this +## Running and modifying this plugin ### With mvn - 1. Go into `blueocean-plugin` and run `mvn hpi:run` in a terminal. (mvn clean install from the root of the project is always a good idea regularly!) 2. From this directory, run `gulp bundle:watch` to watch for JS changes and reload them. 3. Open browser to http://localhost:8080/jenkins/blue/ to see this diff --git a/blueocean-plugin/README.md b/blueocean-plugin/README.md index 80e963ac..824fd50a 100644 --- a/blueocean-plugin/README.md +++ b/blueocean-plugin/README.md @@ -2,12 +2,13 @@ This plugin allows blueocean to run as a plugin inside an existing Jenkins. -## Usage during development +## To start it all up -To use this in development: +To use this in development or to tyre kick: `mvn hpi:run` +(make sure you have run `mvn clean install` from the parent first) Blue Ocean UI: @@ -19,5 +20,40 @@ Embedded Jenkins UI (so you can create some pipelines for fun): This links source from the other modules. So if you make a source change to rest, web or other modules, -it will be applied here. If its a UI module, you will need to run `gulp rebundle` in the UI modules directory -to watch for JS/HTML changes and live reload them. +it will be applied here. If its a UI module, you will need to have gulp installed (http://gulpjs.com/) and run `gulp bundle:watch` in the modules directory that has the JS you want to watch for changes and to have the reloaded live. + +# Running Blue Ocean in development + +If you want to add to some extension points or mess with the GUI as it is right now, take a look at the `blueocean-dashboard` module (actually a plugin). Also take a look at: https://github.com/cloudbees/blueocean-sample-pipeline-result-ext-plugin for an example of an plugin that augments Blue Ocean. + +Run in this directory: + +`mvn hpi:run` + + +## Verify it's working + + curl -v -X GET http://localhost:8080/jenkins/blue/rest/organizations/jenkins/ + +Should print: + + {"name":"jenkins"} + +Why not also try: `curl http://localhost:8080/jenkins/blue/rest/organizations/jenkins/pipelines/` + +Load it in browser to see your ui code: + + http://localhost:8080/jenkins/blue + +Load it in the browser to see the embedded Jenkins: + + http://localhost:8080/jenkins + +Look in blueocean-dashboard plugin for instructions on how to make changes to GUI code. + + + + + + + diff --git a/blueocean-rest/README.md b/blueocean-rest/README.md index f8c9570a..3d8f88e6 100644 --- a/blueocean-rest/README.md +++ b/blueocean-rest/README.md @@ -1,20 +1,24 @@ +# REST api for Blue Ocean components + +This defines the http/REST like interface that Blue Ocean components use. + # Usage ## Crumbs -Jenkins usually requires a "crumb" with posted reuqests to prevent request forgery and other shenanigans. +Jenkins usually requires a "crumb" with posted requests to prevent request forgery and other shenanigans. To avoid needing a crumb to POST data, the header `Content-Type: application/json` *must* be used. -## Run BlueOcean plugin +## Run Blue Ocean plugin cd bluecoean-plugin mvn hpi:run -This will launch jenkins with BlueOcean plugin. +This will launch a development Jenkins instance with the Blue Ocean plugin and this plugin ready to go. BlueOcean UI is available at: - http://localhost:8080/jenkins/bo + http://localhost:8080/jenkins/blue BlueOcean rest API base URL is: diff --git a/blueocean-web/README.md b/blueocean-web/README.md index e1b59496..383091d3 100644 --- a/blueocean-web/README.md +++ b/blueocean-web/README.md @@ -1,60 +1,21 @@ -# UI Plugin +# Web middleware + +This module mostly contains middleware for serving up "/blue" GUI. +In general, you shouldn't need to modify stuff in for plugins or features as it is infrastructure. Move along. -This is the main UI guts of blueocean. Javascript magic happens here as well as some core web classes. Look for blueocean.js for excitement. -# Running Blue Ocean in development +## how this works with Javascript -If you want to add to some extension points, take a look at the `blueocean-dashboard` module (actually a plugin) for an example. +Jenkins-js-modules and friends are used to power this. Look in `src/main/js` in any plugin. -## Firstly build all modules from root +If you wish to make changes to blueocean.js in this plugin, then you will need to install gulp (http://gulpjs.com/), and then run `cd blueocean-plugin && mvn hpi:run` in a separate terminal. - cd .. - mvn clean install - - -## Run it in plugin dev mode +Then run: -To hack on blue ocean UI, you will want to run it embedded in a Jenkins you can add jobs to and so on. -To do this, use the `blueocean-plugin` module: - - cd blueocean-plugin - mvn hpi:run - -## Verify it's working - - curl -v -X GET http://localhost:8080/jenkins/blue/rest/organizations/jenkins/ - -Should print: - - {"name":"jenkins"} - -Why not also try: `curl http://localhost:8080/jenkins/blue/rest/organizations/jenkins/pipelines/` - -Load it in browser to see your ui code: - - http://localhost:8080/jenkins/blue - -Load it in the browser to see the embedded Jenkins: - - http://localhost:8080/jenkins - - -## Javascript and HTML development - -Jenkins-js-modules and friends are used to power this. Look in `src/main/js`. - -If you wish to make changes to blueocean.js, then you will need to install gulp (http://gulpjs.com/), and then run (in a separate terminal to mvn hpi:run): - -``` -$ cd blueocean-web +``` $ gulp bundle:watch ``` -(or run gulp, after each change) in the `blueocean-web` directory. This will pick up any changes. +(or run gulp, after each change) in this directory. This will pick up any changes. If you are editing any other UI modules, run the same in their respective directories. - - - - -