swim/README.md

# swim - project board software

swim is a project/task management helper that organizes projects into "swim lanes". The lanes can contain "stories" that represent a subproject. These subprojects can have titles, descriptions, assigned users, a point representation of their difficulty, a task list, and comments. Stories can be moved around within and between lanes to represent their current state in the project. A common layout for simple projects is to have three lanes: backlog, active, complete; but many other working models are possible.

## Building and Installing

You will need a Go compiler. Testing on early versions has not been done, but suffice to say you should likely not need the latest cutting edge Go version to compile _swim_.

A Makefile has been provided with targets for `make` to just build in the local directory and `[sudo] make install` to install on the system along with the manpage. If you do not care about the manpage you can run `go build` or `go install`.

## Usage

_swim_ has a number of commands and "hot" keys. They will be detailed in this section, but are also avialable via the manpage.

The main view of the program is the `swim lane` view. You can add as many lanes as you like. Lanes have titles and contain stories. A story shows up in a lane as the story title on the first row of the card and the assigned users (initials) and the number of story points together on the second row of the card.

![a screenshot of the swim lane view of the application 'swim'](swim-lane-view.png)

When viewing a story you will see the story title, when the story was last updated, the user(s) assigned to the story, a description of the story, a checklist in the form of tasks, and a comments section.

![a screenshot of the story view of the application 'swim'](swim-story-view.png)

## Command Line Options

_swim_ has two command line flags: `-color` and `-h`. `-color` is detailed in its [own section](#colors) below. `-h` prints help text.

There is also one command line option or subcommand: `init`. Running `swim init` will create a swim file in the current working directory with three lanes (backlog, active, complete). The file will be named after the directory it is found in. So, if the working directory is `~/projects/myproject`, the file created will be `~/projects/myproject/myproject.swim`. This provides a quick way to get a board going without having to go through boilerplate steps. It is completely optional (it is not hard to build out a customized board).

### "Hot" Keys

These can be pressed at appropriate times to quickly control the board/program.

#### Lane View

These keys have the following effect while looking at the main 'swim lane' view:

- `h` - Move focus one lane to the left
- `j` - Move focus one story down
- `k` - Move focus one story up
- `l` - Move focus one lane to the right
- `H` - Move focused story one lane to the left
- `J` - Move focused story one story down in the current lane
- `K` - Move focused story one story up in the current lane
- `L` - Move focused story one lane to the right
- `Q` - Quit swim immediately
- `N` - Create a new lane, will query for lane name
- `n` - Create a new story in the focused lane, will query for story name
- `<Enter>` - View the currently focused story
- `g` - Move focus to the first (top) story in the currently focused lane
- `G` - Move focus to the last (bottom) story in the currently focused lane
- `:` - Enter command mode; all commands work from any view/screen
- `+` - Zoom in; show fewer, but wider, lanes on the screen at one time
- `-` - Zoom out; show more, but narrower, lanes on the screen at one time

#### Story View

While looking at a story's detailed view these keys have the following effects to the story being viewed:

- `h` - Return to 'swim lane' view
- `j` - Scroll down
- `k` - Scroll up
- `g` - Scroll to top
- `G` - Scroll to bottom
- `:` - Enter command mode; all commands work from any view
- `c` - Add a new comment; will query for comment value
- `t` - Add a new task; will query for task value
- `T` - Set a new title; will query for title value
- `d` - Set a new description; will query for description value
- `D` - Delete a task; will query for task number
- `u` - Toggle assigned user(s); will query for a space separated list of users and will toggle each user's state on/off (if they are already on the card they will be removed, otherwise they will be added)
- `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `0` - Will toggle the task with the given number (un)complete. `0` represents `10`. This is quicker than having to type `:toggle 2` or the like


### Commands

Command mode can be accessed via the "hot" key `:`. Most of the commands can be abbreviated. For example: `:set story points 2` could also be `:s s p 2` or `:s st points 2`. In most cases any portion of the word will work.

This tree style listing shows commands and their sub-commands. Anything inside of `{curly braces}` represents an optional value that can be added. These optional values can be as many words as you like and the command that you are issuing will put them together as needed. If an optional value is not passed as a part of the command then the user will be queried for the value and their response will be verified (with a yes/no/cancel prompt).

- `create`
    - `lane`
        - `{title}`
    - `story` - Will be added to the currently selected lane
        - `{title}`
    - `task` - Will be added to the currently selected story
        - `{value}`
    - `coment`
        - `{value}`
- `delete`
    - `lane` - Always refers to the currently selected lane
    - `story` - Always refers to the currently selected story
    - `task` - Always refers to the currently selected story
        - `{task number}`
- `quit`
- `regex` - Uses golang style regular expressions
    - `board`
        - `title`
            - Expression in the form: `/[match expression]/[replacement]/`
    - `lane`
        - `title`
            - Expression in the form: `/[match expression]/[replacement]/`
    - `lanes` - Applies the expression to all lanes, abbreviating `lanes` is not allowed
        - `title`
            - Expression in the form: `/[match expression]/[replacement]/`
    - `story`
        - `title`
            - Expression in the form: `/[match expression]/[replacement]/`
        - `description`
            - Expression in the form: `/[match expression]/[replacement]/`
    - `stories` - Applies the expression to all stories in the current lane, abbreviating `stories` is not allowed
        - `title`
            - Expression in the form: `/[match expression]/[replacement]/`
        - `description`
            - Expression in the form: `/[match expression]/[replacement]/`
    - `stories!` - Applies the expression to all stories on the board (use with care), abbreviating `stories!` is not allowed
        - `title`
            - Expression in the form: `/[match expression]/[replacement]/`
        - `description`
            - Expression in the form: `/[match expression]/[replacement]/`
- `set`
    - `board`
        - `title`
            - `{value}`
    - `lane` - Always refers to the currently selected lane
        - `title`
            - `{value}`
    - `story` - Always refers to the currently selected story
        - `title`
            - `{value}`
        - `description`
            - `{value}`
        - `points`
            - `{value}`
        - `user`
            - {space separated list of usernames to (un)assign}
- `toggle` - Marks a task as (in)complete. Always refers to the currently selected story
    - `{task number}`
- `user` - Always refers to the currently selected story
    - `{space separated list of usernames to (un)assign}`

- `write`
    - `{path}` - Will use the current path if nothing is passed
- `wq` - Same as `write`, but quits afterward
    - `{path}` - Will use the current path if nothing is passed

## Files

swim writes data to files as json data representing program state. This allows swim files to be flexible. In theory an alternate client could be built around the same data models and interoperate pretty easily with swim, allowing end users choice of control application for underlying data.

## Colors

Reliably getting a value for what color modes are supported for a given terminal is tricky business. _swim_ does some sniffing and makes a conservative guess for what color mode your terminal will support. Three modes are supported: 4-bit (Simple), 8-Bit (256), and 24-Bit (True). The colors can be found in the file `colors.go` and can be edited and recompiled if desired. They use [ansi escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) and work in a mostly straightforward manner.

Any of the three color modes can be forced with the runtime flag `-color`. For example:

- `swim -color simple ./my-file.swim`
- `swim -color 256 ./my-file.swim`
- `swim -color true ./my-file.swim`
- `swim -color none ./my-file.swim`

That last one, `none`, will never be used automatically, but can be passed with the given flag to turn off color and just use your terminal's foreground/background colors (plus occasional bold and inverse coloring).

## Sizing and Signals

_swim_ will automatically resize and redraw when your terminal is resized. It also handled common signals well, allowing for suspend/resume job control to work nicely and for other signals (^c and ^d come to mind) to behave as expected.

## Examples

A file, `swim.json`, is included with this repository. It has been used to track work on the project itself (at least since file i/o was added) and can serve as a simple example and a way to try navigating around the program with some data already present.

## License

A license file is included in the repo. If for some reason you have this readme but not the license file, it can be viewed on the web via [floodgap](https://www.floodgap.com/software/ffsl/license.html).