Mercurial > hg > thermostat-ng
changeset 1:af1ff6ea8e2a
Some docs cleanups
review-thread: http://icedtea.classpath.org/pipermail/thermostat/2017-May/022975.html
reviewed-by: jkang
| author | Mario Torre <neugens.limasoftware@gmail.com> |
|---|---|
| date | Mon, 08 May 2017 14:51:37 +0200 |
| parents | df7dc704632a |
| children | 7cd7c2bb65d0 |
| files | HACKING LICENSE OFL.txt README README.api README.fontawesome |
| diffstat | 6 files changed, 11 insertions(+), 603 deletions(-) [+] |
line wrap: on
line diff
--- a/HACKING Mon Mar 06 16:04:00 2017 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,181 +0,0 @@ -HACKING -======= - -This guide provides an introduction and some rules for developing -Thermostat. - -See also: http://icedtea.classpath.org/wiki/Thermostat/DevelopmentStyleGuide - - -Layout ------- - -Thermostat code is organized in a few different ways. - -The core functionality is split into `common`, `client`, and `agent` -modules (and their submodules). - -The rest is split functionally: `storage` contains storage-related -code, `launcher` is the main launcher and so on. To introduce a new -functional component of thermostat, put it in its own top-level -directory and make it a new module. - -Major new features should go into their own module(s). Each module is -an OSGi bundle. - -Plugins shipped with thermostat are put into their own separate -top-level modules in the source. Examples include `host-cpu` and -`vm-gc`. For the sake of consistency, name a vm-specific plugin with a -`vm-` prefix and a host-only plugin with a `host-` prefix. - -A module that gathers a particular data is generally split as follows: - -- `common`: shared code between the agent and the client -- `agent`: code that should only be executed on the agent -- `client`: code that should be executed client-side only -- `cli`: code that is meant for the command line only -- `swing`: code meant for the graphical runtime environment only -- `distribution`: a non-code module that bundles the entire plugin - into a single zip file. - -Use a single package as the module root package. Base it on the name -of the module. For a `vm-foo` module, use -`com.redhat.thermostat.vm.foo`. Avoid vague terms like `thermostat` -and `utils` in the package names. - -POM Files ---------- - -Define the version for any dependency in the root (or main) `pom.xml` -file. Define it as a property named `project-name.version`. Example: -`commons-cli.version`. - -If the OSGi version differs from the project version, define it as a -separate property `project-name.osgi-version`. Example: -`commons-codec.osgi-version`. - - -Code Style ----------- - -The standard license header goes on top of every file. It's enforced -using a maven plugin. Use `mvn license:format` to generate/update it. -The license template is defined in `src/license/header.txt`. - -Above all, be consistent with the style of code you are modifying. - -Formatting Style: -- Spaces instead of tabs -- Avoid trailing spaces - -Use this style: - - public class Foo { - public void foo(Bar bar, Baz baz) { - try { - if (possible) { - doFoo(bar); - } - } catch (FooException | BarExcetpion e) { - e.printStackTrace(); - } - } - } - - -UI Message Style ----------------- - -Messages displayed in progress handles should be short but mostly-complete -sentence fragments. Overly verbose messages clutter the UI, but overly curt -messages maybe not provide the user with enough information to distinguish -which task a progress notification belongs to. - -Additionally, messages should be properly capitalized, and should be -terminated with the Unicode horizontal ellipsis character ('\u2026') -immediately following the final character of the message itself - in other -words, there should be no space between the message and the ellipsis. - -This is a good example of a progress handle message: - -"Starting profiling\u2026" - -The following are bad examples of the same message: - -"Starting\u2026" (what task is starting?) -"Profiling\u2026" (what is profiling doing?) -"Starting profiling..." (these are three periods, not an ellipsis character) -"Starting profiling \u2026" (space before the ellipsis) -"starting profiling\u2026" (not capitalized correctly) - - -Tests ------ - -Every class `Foo` should have a unit test named `FooTest`. The test -should be in the same package. Test-specific hooks should be package -private in the original class. - -GUI code should be unit tested using FEST and Caciocavallo. - -For complex features, an integeration test should also be added if -possible. Integration tests go in the `integration-tests` module. - - -Documentation -------------- - -Add appropriate documentation, for both developers and users. - -Use the active voice for all user-facing documentation. - -Classes that are part of the public API should have some documentation -describing their use and linking to other relevant classes. - -Commands should have both summaries and descriptions. Write both the -summary and description in active and action-oriented style. For the -summary prefer direct and short forms: 'foo the bar' over 'foos the -bar by bazing the ...'. - -A command's summary is displayed as a short help message. Make it short. -Do not capitalize it, or end it with a period. - -A command's description is displayed as a long help message. Make it -fully describe the command, including its actions and side-effects. -Describe all options. Use full sentences, each ending with a period. - -Don't forget to update the man page (`distribution/docs/thermostat.1`) -when changing an existing command. - -Commits -------- - -All commits must build and pass all unit tests. - -Commits require review. Before pushing a commit, make sure it is -reviewed on the mailing list by at least one other developer and any -concerns have been resolved. - -Commit messages are normally of the form: - - Short summary of the fix - - A detailed description of fix with additional details, like steps to - reproduce the problem, explanation of any subtle changes, links to - docs or anything that might help when examining this changeset in the - future to figure out why a change was done. - - Also, try and keep commit message lines to under 80 characters. - - You can also link a bug using the PR notation. Something like "This - commit fixes PR666", which refers to a bug with the id 666 on - http://icedtea.classpath.org/bugzilla/ - - The last few lines are important. They list the reviewers and a link to - the mailing list thread (or the equivalent) where this patch was - reviewed. - - Reviewed-by: userid1, userid2, userid3 - Review-thread: http://link.to.mailing.list.discussion.example.com/ - -
--- a/LICENSE Mon Mar 06 16:04:00 2017 +0100 +++ b/LICENSE Mon May 08 14:51:37 2017 +0200 @@ -23,11 +23,3 @@ not obligated to do so. If you do not wish to do so, delete this exception statement from your version. --------------------------------------------------------------------------------- -Additional files and licenses --------------------------------------------------------------------------------- - -Thermostat uses Font Awesome by Dave Gandy (http://fontawesome.io) as primary -icon resource, distributed under the SIL OFL 1.1 (http://scripts.sil.org/OFL). -A copy of the OFL 1.1 license is also included and distributed with Thermostat. -
--- a/OFL.txt Mon Mar 06 16:04:00 2017 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,93 +0,0 @@ -Font Awesome Copyright by Dave Gandy, http://fontawesome.io - -This Font Software is licensed under the SIL Open Font License, Version 1.1. -This license is copied below, and is also available with a FAQ at: -http://scripts.sil.org/OFL - - ------------------------------------------------------------ -SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 ------------------------------------------------------------ - -PREAMBLE -The goals of the Open Font License (OFL) are to stimulate worldwide -development of collaborative font projects, to support the font creation -efforts of academic and linguistic communities, and to provide a free and -open framework in which fonts may be shared and improved in partnership -with others. - -The OFL allows the licensed fonts to be used, studied, modified and -redistributed freely as long as they are not sold by themselves. The -fonts, including any derivative works, can be bundled, embedded, -redistributed and/or sold with any software provided that any reserved -names are not used by derivative works. The fonts and derivatives, -however, cannot be released under any other type of license. The -requirement for fonts to remain under this license does not apply -to any document created using the fonts or their derivatives. - -DEFINITIONS -"Font Software" refers to the set of files released by the Copyright -Holder(s) under this license and clearly marked as such. This may -include source files, build scripts and documentation. - -"Reserved Font Name" refers to any names specified as such after the -copyright statement(s). - -"Original Version" refers to the collection of Font Software components as -distributed by the Copyright Holder(s). - -"Modified Version" refers to any derivative made by adding to, deleting, -or substituting -- in part or in whole -- any of the components of the -Original Version, by changing formats or by porting the Font Software to a -new environment. - -"Author" refers to any designer, engineer, programmer, technical -writer or other person who contributed to the Font Software. - -PERMISSION & CONDITIONS -Permission is hereby granted, free of charge, to any person obtaining -a copy of the Font Software, to use, study, copy, merge, embed, modify, -redistribute, and sell modified and unmodified copies of the Font -Software, subject to the following conditions: - -1) Neither the Font Software nor any of its individual components, -in Original or Modified Versions, may be sold by itself. - -2) Original or Modified Versions of the Font Software may be bundled, -redistributed and/or sold with any software, provided that each copy -contains the above copyright notice and this license. These can be -included either as stand-alone text files, human-readable headers or -in the appropriate machine-readable metadata fields within text or -binary files as long as those fields can be easily viewed by the user. - -3) No Modified Version of the Font Software may use the Reserved Font -Name(s) unless explicit written permission is granted by the corresponding -Copyright Holder. This restriction only applies to the primary font name as -presented to the users. - -4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font -Software shall not be used to promote, endorse or advertise any -Modified Version, except to acknowledge the contribution(s) of the -Copyright Holder(s) and the Author(s) or with their explicit written -permission. - -5) The Font Software, modified or unmodified, in part or in whole, -must be distributed entirely under this license, and must not be -distributed under any other license. The requirement for fonts to -remain under this license does not apply to any document created -using the Font Software. - -TERMINATION -This license becomes null and void if any of the above conditions are -not met. - -DISCLAIMER -THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT -OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE -COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL -DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM -OTHER DEALINGS IN THE FONT SOFTWARE.
--- a/README Mon Mar 06 16:04:00 2017 +0100 +++ b/README Mon May 08 14:51:37 2017 +0200 @@ -1,29 +1,12 @@ - -CONTENTS: --------------------------------------------------------------------------------- - -0. ABOUT -1. REQUIREMENTS -2. BUILDING THERMOSTAT -3. RUNNING THERMOSTAT -3.1 PASSING JVM SPECIFIC OPTIONS -3.2 GNOME KEYRING -4. EXTENDING THERMOSTAT -5. SYSTEM PROPERTIES -6. LICENSE -7. REFERENCES - - --------------------------------------------------------------------------------- -0. ABOUT - -Thermostat is a monitoring, profiling and serviceability tool for Java -applications. It allows users to examine, trace and profile various -attributes of a running JVM (and its environment) to understand how it +Thermostat is a micro-services based monitoring, profiling and serviceability +tool for Java applications. It allows users to examine, trace and profile +various attributes of a running JVM (and its environment) to understand how it is behaving. -Please use the discussion list for any questions, concerns or -comments. +Please use the discussion list for any questions, concerns or comments. + +User Guide: +- http://icedtea.classpath.org/wiki/Thermostat/UserGuide Additional resources: - Homepage: http://icedtea.classpath.org/thermostat/ @@ -31,235 +14,9 @@ - Discussion List: http://icedtea.classpath.org/mailman/listinfo/thermostat - Bug tracker: http://icedtea.classpath.org/bugzilla/ - --------------------------------------------------------------------------------- -1. REQUIREMENTS - -* OpenJDK 7 (or OpenJDK 8) - - Thermostat requires at least Java 7 to build and run. Thermostat has - been tested with OpenJDK 7 and 8. Other VMs or versions may or may - not work. Thermostat needs a full JDK to run. It will not work - correctly with just a JRE. - -* Maven (it will download all the java dependencies for you) -* Make, GCC + autoconf -* MongoDB server - - Thermostat requires mongodb (http://www.mongodb.org/) server >= 2.0.0. - - On Fedora, you can obtain it via: - - yum install mongodb-server - -* Either a /etc/os-release file or lsb_release -* Gnome Keyring Daemon development libraries plus pkg-configs. Either libsecret - based or a libgnome-keyring based solution is supported. -* GTK 2+ development libraries plus pkg-configs - - Gnome Keyring/GTK2+ development libraries are required at build time. - - You should check your distribution for the exact name of the libraries, on - Fedora based distributions you can obtain it via: - - dnf install libsecret-devel gtk2-devel - - or - - yum install libgnome-keyring-devel gtk2-devel - - on RHEL/CentOS 6.x via: - - yum install gnome-keyring-devel gtk2-devel - - On Debian (and probably Ubuntu): - - aptitude install libgnome-keyring-dev libgtk2.0-dev - --------------------------------------------------------------------------------- -2. BUILDING THERMOSTAT - -Thermostat consists of: - * CLI client - * Swing GUI client - * The thermostat agent - * The web service layer - -2.1. - Run "mvn clean install". All tests should pass and the build should - succeed. It requires a graphical environment for the ui tests. - - Thermostat also includes a Makefile wrapping the maven build. In most - cases, simply running "make" will accomplish the same as "mvn clean - install". Please see environment variables near beginning of - Makefile for some options that can be customized. - - You can skip the tests phase by running: - - mvn -Dmaven.test.skip=true clean install - - If maven is too chatty, you can try to pass the "-q" option: - - mvn -q -Dmaven.test.skip=true clean install - -2.2. - The resulting Thermostat system can now be found under the directory - distribution/target/image. - - If you want to install thermostat to a system location, use the - thermostat.home maven property to set that at build time: - - mvn -Dthermostat.home=/path/to/install/thermostat - - You will have to move the resulting build to the path manually. This property - sets up mostly distribution related files (for services) that need the full - path to Thermostat. It is not required to run thermostat normally. - --------------------------------------------------------------------------------- -3. RUNNING THERMOSTAT - - DISCLAIMER: These are simplified instructions as to how to set up and run - Thermostat on a local system. For production systems see - instructions in our user guide (see REFERENCES). - - cd into distribution/target/image directory just created - - Run GUI thermostat: - - Start thermostat local (this will run setup silently on first run): - bin/thermostat local - - Or run CLI thermostat: - - Run CLI-based setup with: - bin/thermostat setup -c - - Start the agent and the db: - bin/thermostat web-storage-service - - Start the shell client: - bin/thermostat shell - - Use the help command in order to find out about all available commands: - bin/thermostat help - -See also the user guide in the REFERENCES section of this document. - - -3.1. PASSING JVM SPECIFIC OPTIONS TO THERMOSTAT - -In some cases, it may be desirable to pass arguments to the virtual machine, -for example to increase memory or change the look and feel for the Swing Client. - -Thermostat follows a well established convention to enable this: options that -start with -J are not passed to the thermostat launcher, but instead to the -JVM itself. - -For example, this command launches thermostat with the Nimbus Look and Feel, -rather then the default one: - -bin/thermostat gui \ - -J-Dswing.defaultlaf=javax.swing.plaf.nimbus.NimbusLookAndFeel - - -3.2. GNOME KEYRING AND THERMOSTAT - -Thermostat includes support to store user credentials in the Gnome Keyring -daemon, if the user wishes. If this is not available at runtime, no credentials -will be stored. - --------------------------------------------------------------------------------- -4. EXTENDING THERMOSTAT - -Please see the HACKING file for more development information on thermostat -itself. - -If you are writing a plugin for thermostat, the README.api file contains a list -of public/support API of thermostat. - --------------------------------------------------------------------------------- -5. SYSTEM PROPERTIES - -Although Thermostat by default is configured to behave in the best possible -way, there is a number of system properties that allows tweaking the behaviour -of specific areas of the platform. - -Here follows the description for the release -referred by this README. Please, refer to -[3.1. PASSING JVM SPECIFIC OPTIONS TO THERMOSTAT] for an explanation -on how to pass system properties to Thermostat. - -IMPORTANT NOTE: Those properties should be considered internal and -may not be used or available in all the releases. Likewise, defaults may -change at any given time without notice. - -* Font Tweaks, Swing GUI only - - skip.system.fonts=<boolean> - -By default, Thermostat tries to use the same fonts used by GTK on the -currently running Desktop. When this property is set to false, the process -is skipped. - -This property is only valid if the default look and feel is used, otherwise -is ignored. - -* Windows Translucency, Swing GUI only - - com.redhat.thermostat.popup.opaque=<boolean> - -By default, Thermostat tries to use translucency popup menus to add a -subtle effect to its user interface. The user can request fully opaque -windows to be used instead, by setting this property to false. - -Note that not all desktop environment support transparency, so this -property may not have any effect. - - com.redhat.thermostat.popup.transparency=<float> - -If transparent windows are used, this property influences the amount of -transparency of the windows. The valid range is 0.0 for fully transparent -and 1.0 for fully opaque, the default value is 0.90. - -* Mongo Storage Profiling, Mongo Storage only - - thermostat.storage.mongo.profile=<boolean> - -Thermostat has some instrumentation code to perform analysis of the -backend databases. In the case of MongoDB, it is possible to run additional -analysis by using Mongo profiling features. The default is to run MongoDB -without profiling support, to turn profiling on this property should be set -to true. This option has only effect when Thermostat is directly responsible -to start the database backend, is ignored otherwise. - - thermostat.storage.mongo.profile.slowms=<integer> - -This property has only effect in conjunction with -"thermostat.storage.mongo.profile=true" and controls the threshold in -milliseconds to decide if a database operation is considered "slow". The -default is 100. - -* Queued Storage Thread Pool Size - - com.redhat.thermostat.storage.queue.poolSize=<integer> - -The above property is used to override the desired thread pool size. The size is -capped at size 100 (the default if no property is specified). This is because -Linux systems usually enforce a per-user process limit of 1024 (ulimit -u). - -The above upper bound can be lifted by setting the following property to true: - - com.redhat.thermostat.storage.queue.unbounded=<boolean> - --------------------------------------------------------------------------------- -6. LICENSE +The project consist of multiple repositories with multiple projects, each +repository has specific READMEs with instructions. Thermostat itself is licensed under GPLv2 with Classpath Exception. Please see -the LICENSE file for more details about the licenses of Thermostat and other -projects used. - --------------------------------------------------------------------------------- -7. REFERENCES - - User Guide: - http://icedtea.classpath.org/wiki/Thermostat/UserGuide +the LICENSE file in each project directory for more details about the licenses +of Thermostat and other projects used.
--- a/README.api Mon Mar 06 16:04:00 2017 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,61 +0,0 @@ -Public API -========== - -The public supported API of thermostat consists of the following packages: - - - com.redhat.thermostat.agent - - com.redhat.thermostat.agent.command - - com.redhat.thermostat.agent.config - - com.redhat.thermostat.agent.utils - - com.redhat.thermostat.agent.utils.management - - com.redhat.thermostat.annotations - - com.redhat.thermostat.backend - - com.redhat.thermostat.client.cli - - com.redhat.thermostat.client.command - - com.redhat.thermostat.client.core - - com.redhat.thermostat.client.core.controllers - - com.redhat.thermostat.client.core.progress - - com.redhat.thermostat.client.core.views - - com.redhat.thermostat.client.swing - - com.redhat.thermostat.client.swing.components - - com.redhat.thermostat.client.swing.components.models - - com.redhat.thermostat.client.ui - - com.redhat.thermostat.common - - com.redhat.thermostat.common.cli - - com.redhat.thermostat.common.command - - com.redhat.thermostat.common.config - - com.redhat.thermostat.common.model - - com.redhat.thermostat.common.portability - - com.redhat.thermostat.common.ssl - - com.redhat.thermostat.common.tools - - com.redhat.thermostat.common.utils - - com.redhat.thermostat.launcher - - com.redhat.thermostat.plugin.validator - - com.redhat.thermostat.service.process - - com.redhat.thermostat.shared.config - - com.redhat.thermostat.shared.locale - - com.redhat.thermostat.storage.config - - com.redhat.thermostat.storage.core - - com.redhat.thermostat.storage.core.auth - - com.redhat.thermostat.storage.dao - - com.redhat.thermostat.storage.model - - com.redhat.thermostat.storage.monitor - - com.redhat.thermostat.storage.query - - com.redhat.thermostat.storage.testutils - - com.redhat.thermostat.utils.keyring - - - -Internal API ------------- - -A number of packages are public (either OSGi or not) but should be considered -internal. - - - c.r.t.main - - c.r.t.shared.perflog - - c.r.t.*.experimental (and subpackages) - - c.r.t.*.internal (and subpackages) - - c.r.t.storage.mongodb (and subpackages) - - c.r.t.web (and subpackages) - - c.r.t.*.noapi
--- a/README.fontawesome Mon Mar 06 16:04:00 2017 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,6 +0,0 @@ -Font awesome location: -./client/swing/src/main/resources/fontawesome-webfont.ttf - -Last update with version 4.5.0, downloaded on Tue, Janauary 12, from https://fortawesome.github.io/Font-Awesome - -Please, refer to FontAwesomeCheatsheet.pdf for the updated list of icons and IDs.