Skip to content

Design Plan

Jump to bottom
Paul Kassianik edited this page Apr 5, 2019 · 1 revision

This is the documentation that came out of the InitialPlan. There will be many additions and changes, so I will make those clear by keeping many of the sections intact.

Jira Integration

Instead of using Basic Authentication as described in the Initial Plan, I decided to instead use API Keys. Although basic auth requires minimal authentication, it seems like Jira seriously discourages their use, and I had a hard time getting it to work consistently. API Keys were much easier to use, and work much more consistently. I also considered using OAuth authentication, but that would require that the administrator of the Jira resource link the application. This is an unneccessary step for an app that just displays and creates boards and issues.

Security

The app requires a couple of parameters to function properly. These parameters should be global variables in Vim and they should be named:

  • g:jiraVimDomainName - This is the resource name, so if your site is example.atlassian.net this value would be example.
  • g:jiraVimEmail - This is the email you would log into Jira with.
  • g:jiraVimToken - This is the API token the app will use to retrieve and put information on your behalf. Information about how to create and optain the token can be found here.

All values should be enclosed in quotes since they will be treated as strings.

You can put them into your .vimrc if you want, or if you have a public config file, you can put them into ~/.vim/plugin/ or the plugin/credentials.vim file of the directory into which you installed this plugin. The latter was specifically added to .gitignore for your convenience.

Sharing Responsibility between Python and Vimscript

The codebase has both Vimscript code and Python code. The delegation of responsibility is as follows:

  • Python will be responsible for accessing and retrieving and sending information to and from the Jira API.
  • Python will be responsible for displaying the information to the user through the use of the vim python plugin. This necessitates that vim be compiled with the python component (if you're on a major OS it probably already is, but if it's not, look in the official Vim repository.
  • Vim will be responsible for providing an interface between the user and the python script. That includes providing functions for various capabilites, providing keybindings, and highlighting.
  • Vim will also be responsible for loading any required python files. Since the python component is not separated as a project and called with py3file commands, all dependencies must be imported manually. (This might actually merit redesign: having all python code in a single package and the vim just imports the package and runs the command).

Design of Python Component

Bundling

There will be a python/requirements.txt file that contain all of the necessary packages and version restrictions. That way you want a virtual env to run this in you can easily install of the necessary applications in there.

Class Design

The Python code will be located in three directories:

  • python/boards
  • python/issues
  • python/common

The first two directories contain python code related to boards and issues respectively. There will be one file per function, so for each vimscript function that requires information from Jira there will be a file in one of these two directories.

The last directory contains helper objects and classes. Currently it contains two files: connection.py and board.py that contain the classes for connections to jira and a board respectively.

Display Format

The primary goal should be the ability to load, display, and edit jira Issues. So for now we only need two main view formats:

  • Board view
  • Issue view

Board View

The Board view will show the board for particular project. The format will contain sections for every "Column" and every line will contain an issue header with some infomation. I'm planning to later add a vertical layout more akin to the layout native to Jira, so the possibility of extension of the layout should be considered when writing code. Every issue line should be able to lead the Issue view for that particular issue. The line of the cursor will be highlighted. It will have the jiraboardview filetype and have a special syntax highlight.

(Not Implemented)

The way to jump between sprints will be by having sections define different scripts and convenient folding.

Issue View

The Issue view will contain all information about the jira issue in question. Fields with editable custom text will have unmodifiable headers, e.g.

Title: Sample Text
Description: This is a sample issue that needs to be fixed

where the Title: and Description: would not be removable with normal vim commands. The only way to remove an optional field would be through a separate mapping. These headers would also be syntax highlighted, and special Vim Sections would be applied to this type of buffer. I'm looking to optimize the approach in this vim plugin for forms.

For fields that have predefined value options (like Priority or Assignee) will have dropdowns a la Neocomplete or YouCompleteme. In fact, the latter is written in python so it might be better for this particular project.

The Issue will have the jiraissueview filetype.

Clone this wiki locally