ttygroup/boartty
Code Issues Proposed changes

Update README and install sample configs

Browse Source 
Change-Id: Iac32f7a02f29622b618940a5a5ba4254f650f09f
This commit is contained in:
James E. Blair 2014-08-31 17:58:43 -07:00
parent e2c9eb27d1
commit 266467493d
7 changed files with 349 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
CONTRIBUTING.rst
View File

@ -1,3 +1,6 @@
Contributing
============
To browse the latest code, see: https://git.openstack.org/cgit/stackforge/gertty/tree/
To clone the latest code, use `git clone git://git.openstack.org/stackforge/gertty`
@ -11,3 +14,47 @@ that links to your launchpad account). Example::
# Do your commits
$ git review
# Enter your username if prompted
Philosophy
----------
Gertty is based on the following precepts which should inform changes
to the program:
* Support large numbers of review requests across large numbers of
projects. Help the user prioritize those reviews.
* Adopt a news/mailreader-like workflow in support of the above.
Being able to subscribe to projects, mark reviews as "read" without
reviewing, etc, are all useful concepts to support a heavy review
load (they have worked extremely well in supporting people who
read/write a lot of mail/news).
* Support off-line use. Gertty should be completely usable off-line
with reliable syncing between local data and Gerrit when a
connection is available (just like git or mail or news).
* Ample use of color. Unlike a web interface, a good text interface
relies mostly on color and precise placement rather than whitespace
and decoration to indicate to the user the purpose of a given piece
of information. Gertty should degrade well to 16 colors, but more
(88 or 256) may be used.
* Keyboard navigation (with easy-to-remember commands) should be
considered the primary mode of interaction. Mouse interaction
should also be supported.
* The navigation philosophy is a stack of screens, where each
selection pushes a new screen onto the stack, and ESC pops the
screen off. This makes sense when drilling down to a change from
lists, but also supports linking from change to change (via commit
messages or comments) and navigating back intuitive (it matches
expectations set by the web browsers).
* Support a wide variety of Gerrit installations. The initial
development of Gertty is against the OpenStack project's Gerrit, and
many of the features are intended to help its developers with their
workflow, however, those features should be implemented in a generic
way so that the system does not require a specific Gerrit
configuration.

158
README.rst
View File

@ -22,90 +22,104 @@ As compared to the web interface, the main advantages are:
repos, a single command instructs it to checkout a change into that
repo for detailed examination or testing of larger changes.
Installation
------------
It is recommended (but not required) to install Gertty in a
virtualenv. To do set one up::
virtualenv gertty-env
source gertty-env/bin/activate
To install the latest version from the cheeseshop::
pip install gertty
To install from a git checkout::
pip install .
Gertty uses a YAML based configuration file that it looks for at
``~/.gertty.yaml``. Several sample configuration files are included.
You can find them in the examples/ directory of the source
distribution or the share/gertty/examples directory after installation.
Select one of the sample config files, copy it to ~/.gertty.yaml and
edit as necessary. Search for ``CHANGEME`` to find parameters that
need to be supplied. The sample config files are as follows:
**minimal-gertty.yaml**
Only contains the parameters required for Gertty to actually run.
**reference-gertty.yaml**
An exhaustive list of all supported options with examples.
**openstack-gertty.yaml**
A configuration designed for use with OpenStack's installation of
Gerrit.
You will need your Gerrit password which you can generate or retrieve
by navigating to ``Settings``, then ``HTTP Password``.
Gertty uses local git repositories to perform much of its work. These
can be the same git repositories that you use when developing a
project. Gertty will not alter the working directory or index unless
you request it to (and even then, the usual git safeguards against
accidentally losing work remain in place). You will need to supply
the name of a directory where Gertty will find or clone git
repositories for your projects as the ``git-root`` parameter.
The config file is designed to support multiple Gerrit instances. The
first one is used by default, but others can be specified by supplying
the name on the command line.
Usage
-----
Create a file at ``~/.gertty.yaml`` with the following contents::
After installing Gertty, you should be able to run it by invoking
``gertty``. If you installed it in a virtualenv, you can invoke it
without activating the virtualenv with ``/path/to/venv/bin/gertty``
which you may wish to add to your shell aliases. Use ``gertty
--help`` to see a list of command line options available.
servers:
- name: gerrit
url: https://review.example.org/
username: <gerrit username>
password: <gerrit password>
git_root: ~/git/
A sample file with several options configured for use with OpenStack's
Gerrit is available in ``gertty.yaml-sample``.
You can generate or retrieve your Gerrit password by navigating to
Settings, then HTTP Password. Set ``git_root`` to a directory where
Gertty should find or clone git repositories for your projects.
If your Gerrit uses a self-signed certificate, you can add::
verify_ssl: False
To the section.
The config file is designed to support multiple Gerrit instances, but
currently, only the first one is used.
After installing the requirements (listed in requirements.txt), you
should be able to simply run Gertty. You will need to start by
subscribing to some projects. Use 'l' to list all of the projects and
then 's' to subscribe to them.
Once Gertty is running, you will need to start by subscribing to some
projects. Use 'L' to list all of the projects and then 's' to
subscribe to the ones you are interested in. Hit 'L' again to shrink
the list to your subscribed projects.
In general, pressing the F1 key will show help text on any screen, and
ESC will take you to the previous screen.
Gertty works seamlessly offline or online. All of the actions that it
performs are first recorded in a local database (in ``~/.gertty.db``
by default), and are then transmitted to Gerrit. If Gertty is unable
to contact Gerrit for any reason, it will continue to operate against
the local database, and once it re-establishes contact, it will
process any pending changes.
The status bar at the top of the screen displays the current number of
outstanding tasks that Gertty must perform in order to be fully up to
date. Some of these tasks are more complicated than others, and some
of them will end up creating new tasks (for instance, one task may be
to search for new changes in a project which will then produce 5 new
tasks if there are 5 new changes). This will explain why the number
of tasks displayed in the status bar sometimes changes rapidly.
If Gertty is offline, it will so indicate in the status bar. It will
retry requests if needed, and will switch between offline and online
mode automatically.
If Gertty encounters an error, this will also be indicated in the
status bar. You may wish to examine ~/.gertty.log to see what the
error was. In may cases, Gertty can continue after encountering an
error. The error flag will be cleared when you leave the current
screen.
To select text (e.g., to copy to the clipboard), hold Shift while
selecting the text.
Philosophy
----------
Gertty is based on the following precepts which should inform changes
to the program:
* Support large numbers of review requests across large numbers of
projects. Help the user prioritize those reviews.
* Adopt a news/mailreader-like workflow in support of the above.
Being able to subscribe to projects, mark reviews as "read" without
reviewing, etc, are all useful concepts to support a heavy review
load (they have worked extremely well in supporting people who
read/write a lot of mail/news).
* Support off-line use. Gertty should be completely usable off-line
with reliable syncing between local data and Gerrit when a
connection is available (just like git or mail or news).
* Ample use of color. Unlike a web interface, a good text interface
relies mostly on color and precise placement rather than whitespace
and decoration to indicate to the user the purpose of a given piece
of information. Gertty should degrade well to 16 colors, but more
(88 or 256) may be used.
* Keyboard navigation (with easy-to-remember commands) should be
considered the primary mode of interaction. Mouse interaction
should also be supported.
* The navigation philosophy is a stack of screens, where each
selection pushes a new screen onto the stack, and ESC pops the
screen off. This makes sense when drilling down to a change from
lists, but also supports linking from change to change (via commit
messages or comments) and navigating back intuitive (it matches
expectations set by the web browsers).
* Support a wide variety of Gerrit installations. The initial
development of Gertty is against the OpenStack project's Gerrit, and
many of the features are intended to help its developers with their
workflow, however, those features should be implemented in a generic
way so that the system does not require a specific Gerrit
configuration.
Contributing
------------
For information on how to contribute to gertty, please see the
For information on how to contribute to Gertty, please see the
contents of the CONTRIBUTING.rst file.

9
examples/minimal-gertty.yaml Normal file
View File

@ -0,0 +1,9 @@
# This is an example ~/.gertty.yaml file with only the required
# settings.
servers:
- name: CHANGEME
url: https://CHANGEME.example.org/
username: CHANGEME
password: CHANGEME
git-root: ~/git/

37
gertty.yaml-sample → examples/openstack-gertty.yaml
View File

@ -8,27 +8,46 @@ servers:
url: https://review.openstack.org/
username: CHANGEME
password: CHANGEME
git_root: ~/git/
git-root: ~/git/
# This section adds the colors that we will reference later in the
# commentlinks section for test results. You can also change other
# colors here.
palettes:
- name: default
test-SUCCESS: ['light green', '', '']
test-FAILURE: ['light red', '', '']
test-SUCCESS: ['light green', '']
test-FAILURE: ['light red', '']
# Uncomment the next line if your terminal has a white background
# palette: light
# Commentlinks are regexes that are applied to commit and review
# messages. They can be replaced with internal or external links, or
# have colors applied.
commentlinks:
# This matches the job results left by Zuul.
- match: "^- (?P<job>.*?) (?P<url>.*?) : (?P<result>[^ ]+) ?(?P<comment>.*)$"
# This indicates that this is a test result, and should be indexed
# using the "job" match group from the commentlink regex. Gertty
# displays test results in their own area of the screen.
test-result: "{job}"
replacements:
# Replace the matching text with a hyperlink to the "url" match
# group whose text is the "job" match group.
- link:
text: "{job:<42}"
url: "{url}"
# Follow that with the plain text of the "result" match group
# with the color "test-{result}" applied. See the palette
# section above.
- text:
color: "test-{result}"
text: "{result} "
# And then follow that with the plain text of the "comment"
# match group.
- text: "{comment}"
# Match Gerrit change ids, and replace them with a link to an
# internal Gertty search for that change id.
- match: "(?P<id>I[0-9a-fA-F]{40})"
replacements:
- search:
@ -38,7 +57,6 @@ commentlinks:
# This is the query used for the list of changes when a project is
# selected. The default is "status:open"; if you don't want to see
# WIP changes, use a query like this:
#
# change-list-query: "status:open not label:Workflow=-1"
# Uncomment the following line to use a unified diff view instead
@ -50,11 +68,22 @@ commentlinks:
hide-comments:
- author: "^(.*CI|Jenkins)$"
# This section defines customized dashboards. You can supply any
# Gertty search string and bind them to any key. They will appear in
# the global help text, and pressing the key anywhere in Gertty will
# discard the current display stack and replace it with the results of
# the query.
dashboards:
- name: "My changes"
query: "owner:self status:open"
key: "f2"
# Reviewkeys are hotkeys that perform immediate reviews within the
# change screen. Any pending comments or review messages will be
# attached to the review; otherwise an empty review will be left. The
# approvals list is exhaustive, so if you specify an empty list,
# Gertty will submit a review that clears any previous approvals.
# They will appear in the help text for the change screen.
reviewkeys:
- key: 'meta 0'
approvals: []

166
examples/reference-gertty.yaml Normal file
View File

@ -0,0 +1,166 @@
# This is an example ~/.gertty.yaml with an exhaustive listing of
# options with commentary.
# This section lists the servers that Gertty can talk to. Multiple
# servers may be listed; by default, Gertty will use the first one
# listed. To select another, simply specify its name on the command
# line.
servers:
- name: CHANGEME
url: https://CHANGEME.example.org/
username: CHANGEME
password: CHANGEME
git_root: ~/git/
# Each server section can have the following fields:
# A name that describes the server, to reference on the command line. [required]
# - name: sample
# The URL of the Gerrit server. HTTPS should be preferred. [required]
# url: https://example.org/
# Your username in Gerrit. [required]
# username: CHANGEME
# Your password in Gerrit (Settings -> HTTP Password). [required]
# password: CHANGEME
# A location where Gertty should store its git repositories. These
# can be the same git repositories where you do your own work --
# Gertty will not modify them unless you tell it to, and even then the
# normal git protections against losing work remain in place. [required]
# git-root: ~/git/
# The location of Gertty's sqlite database. If you have more than one
# server, you should specify a dburi for any additional servers.
# dburi: ~/.gertty.db
# If your Gerrit server has a self-signed cert (eg, a test server),
# you can set this value to false to turn of certificate validation.
# verify-ssl: true
# By default Gertty logs errors to a file and truncates that file each
# time it starts (so that it does not grow without bound). If you
# would like to log to a different location, you may specify it here.
# log-file: ~/.gertty.log
# Gertty comes with two palettes defined internally. The default
# palette is suitable for use on a terminal with a dark background.
# The "light" palette is for a terminal with a white or light
# background. You may customize the colors in either of those
# palettes, or define your own palette.
# The following alters two colors in the default palette, one color in
# the light palette, and one color in a custom palette. If any color
# is not defined in a palette, the value from the default palette is
# used. The values are a list of at least two elements describing the
# colors to be use for the foreground and background colors.
# Additional elements can specify (in order) the color to use for
# monochrome terminals, the foreground, and background colors to use
# in high-color terminals.
# For a reference of possible color names, see:
# http://urwid.org/manual/displayattributes.html#foreground-and-background-settings
# To see the list of possible palette entries, run "gertty --print-palette".
palettes:
- name: default
added-line: ['dark green', '']
added-word: ['light green', '']
- name: light
filename: ['dark cyan', '']
- name: custom
filename: ['light yellow', '']
# Palettes may be selected at runtime with the "-p PALETTE" command
# line option, or you may set the default palette here:
# palette: light
# Keymaps work the same way as palettes. Only one keymap is defined
# internally, the default keymap. Individual keys may be overridden
# and custom keymaps defined and selected in the config file or the
# command line.
# Each keymap contains a mapping of command -> key(s). If a command
# is not specified, Gertty will use the keybinding specified in the
# default map. More than one key can be bound to a command.
# Run "gertty --print-keymap" for a list of commands that can be
# bound.
keymaps:
- name: default
diff: 'd'
- name: custom
review: ['r', 'R']
# The default keymap may be selected with the '-k KEYMAP' command line
# option, or with the following line:
# keymap: custom
# Commentlinks are regular expressions that are applied to commit and
# review messages. They can be replaced with internal or external
# links, or have colors applied.
commentlinks:
# Match Gerrit change ids, and replace them with a link to an internal
# Gertty search for that change id.
- match: "(?P<id>I[0-9a-fA-F]{40})"
replacements:
- search:
text: "{id}"
query: "change:{id}"
# Any number of commentlink entries may be specified. Start each with
# a "match" key and regex. Named match groups within the regex may be
# used in the replacements section. Any number of replacements may be
# specified. The types of replacement available are:
#
# Text: Plain text whose color may be specified. The color references
# a palette entry.
# - text:
# color: ""
# text: ""
# Link: A hyperlink with the indicated text that when activated will
# open the user's browser with the supplied URL
# - link:
# text: ""
# url: ""
# Search: A hyperlink that will perform a Gertty search when
# activated.
# - search:
# text: "{id}"
# query: "change:{id}"
# This is the query used for the list of changes when a project is
# selected. The default is "status:open".
# change-list-query: "status:open"
# Uncomment the following line to use a unified diff view instead
# of the default side-by-side:
# diff-view: unified
# Uncomment the following lines to Hide comments by default that match
# certain criteria. You can toggle their display with 't'. Currently
# the only supported criterion is "author".
# hide-comments:
# - author: "^(.*CI|Jenkins)$"
# This section defines customized dashboards. You can supply any
# Gertty search string and bind them to any key. They will appear in
# the global help text, and pressing the key anywhere in Gertty will
# discard the current display stack and replace it with the results of
# the query.
dashboards:
- name: "My changes"
query: "owner:self status:open"
key: "f2"
# Reviewkeys are hotkeys that perform immediate reviews within the
# change screen. Any pending comments or review messages will be
# attached to the review; otherwise an empty review will be left. The
# approvals list is exhaustive, so if you specify an empty list,
# Gertty will submit a review that clears any previous approvals.
# They will appear in the help text for the change screen.
reviewkeys:
- key: 'meta 0'
approvals: []
- key: 'meta 1'
approvals:
- category: 'Code-Review'
value: 1
- key: 'meta 2'
approvals:
- category: 'Code-Review'
value: 2

20
gertty/config.py
View File

@ -193,19 +193,11 @@ class Config(object):
return None
def printSample(self):
print """Please create a configuration file ~/.gertty.yaml
filename = 'share/gertty/examples'
print """Gertty requires a configuration file at ~/.gertty.yaml
Example:
Several sample configuration files were installed with Gertty and are
available in %s in the root of the installation.
-----8<-------8<-----8<-----8<---
servers:
- name: gerrit
url: https://review.example.org/
username: <gerrit username>
password: <gerrit password>
git_root: ~/git/
-----8<-------8<-----8<-----8<---
Then invoke:
gertty gerrit
"""
For more information, please see the README.
""" % (filename,)

2
setup.cfg
View File

@ -22,6 +22,8 @@ keywords = gerrit console urwid review
[files]
packages =
gertty
data_files =
share/gertty/examples = examples/*
[entry_points]
console_scripts =