Introduction and project goals

I’ve got a grant to the NLnet foundation for a project to improve the Sequoia-PGP command line sq program:

  • Add important missing functionality.
    • especially compared to GnuPG
    • guided by feedback from actual and potential users and the wisdom of Sequoia developers
  • Add a JSON API to allow sq to be used from scripts.
    • ideally, other programs would use the Sequoia library directly
    • however, using sq from other programs should be easy and secure
    • JSON is a better format than parsing textual output or ad hoc structured data formats
  • Document acceptance criteria and how they are verified automatically.
    • make sure sq does the right thing for its users
    • help keep sq working far into the future

This page documents how I plan to achieve that and what I’ve done so far. I will report on my progress on the Sequoia project blog, and will link to such blog posts from this page.

The public communication of this project will be in the Sequoia issue tracker on gitlab.com, on the Sequoia-PGP project blog, on my personal blog, on the fediverse, on the Sequoia IRC channels, and via other channels. Any deliverables will be posted or advertised via these channels, and linked from this page.

Overview

I represent the project plan using a dependency graph. Each node in the graph represents a milestone, and a milestone may require one or more other milestones to have been completed before that milestone can be started. The graph shows that visually. Individual milestones are described in text below.

It should be noted that as work progresses and more is learned about the project, and as the world changes, the plan will inevitably change. Each milestone can be considered to consist of one or more iterations. When an iteration finishes, it may be necessary to change the plan for future iterations.

Some milestones may be hard to plan for ahead of time, even their scope be unknowable. To avoid scopes from growing too much, and risking failure of the overall project, such risky milestones may be “time boxed”, by excluding parts of the scope and documenting excluded parts in the Sequoia issue tracker. I will update this page as plans change.

I intend to make requests for payment to NLnet about once per calendar month, for any milestones I’ve finished. The milestones in this project plan are to make it easier to do the planning.

Milestone dependency graph

DONE: acceptance_initial

When this milestone has been reached: An initial list of acceptance criteria for sq have been documented based on functionality at the beginning of the project. This will include how to automatically verify that sq fulfills the criteria. The verification is done by Sequoia CI for every change.

This milestone produces a foundational building block for all other development: it sets up the way how sq functionality and acceptance criteria will be documented and verified in an automated way. This is best done early in the process so that it supports development work, rather than done at the end, when it’s more work to do.

Implementation steps:

  • write acceptance criteria and verification scenarios for as much of existing sq functionality as there is time for

Time estimate: 5 days

Deliverable: blog post linking to acceptance criteria documentation

DONE: acceptance_stakeholders

When this milestone has been reached: An initial list of stakeholders for sq has been collected based on personal contacts, and a public call for interested parties to be added to the list is published.

The stakeholders will be interviewed for requirements they have on sq and are expected to review and provide feedback on acceptance criteria and their verification for the duration of the project. They may also be asked to participate in user testing of sq.

The list of stakeholders will not be public, for privacy. However, stakeholders may make their participation publish if they wish.

The stakeholders will form the structured core of the how this project collects feedback. Longer term, the scaffolding for documenting and verifying acceptance criteria will shape how sq is developed in the future based on user needs changing.

Implementation steps:

  • collect list by interviewing Sequoia developers and asking friends
  • write and publish blog post asking for volunteers

Time estimate: 1 day

Deliverable: blog post asking for volunteer stakeholders

DONE: acceptance_interviews

When this milestone has been reached: All listed sq stakeholders have been interviewed about what their acceptance criteria for sq are. The results have been written up and published. Interviews will be conducted via email or video chats and the write-up will hide the identities of the interviewed.

Implementation steps:

  • make list of questions to ask everyone
  • email questions to all stakeholders, also asking for video interview volunteers
  • interview up to ten people, up to an hour each, taking notes
  • write and publish blog post of results

Time estimate: 10 days

Deliverable: blog post describing interview results

Milestone: acceptance_user_test_plan

When this milestone has been reached: An initial plan for user testing the sq command line interface has been written and published. It covers both the human-oriented parts and the JSON API parts of the interface.

The user testing will probably be watching people use sq to achieve specific goals, over a video link. The plan will include the concrete goals to achieve and what is required for them to be considered achieved.

Implementation steps:

  • draft a plan for user testing
  • ask Sequoia developers for feedback on plan
  • plan and test setup for doing the testing
  • write and publish blog post about plan
  • ask stakeholders to volunteer for user testing, co-ordinate times with up up to ten people

Time estimate: 5 days

Deliverable: blog post describing user test plan

Milestone: acceptance_user_test

When this milestone has been reached: The human-oriented parts of the sq command line interface have been user tested according to plan. The results have been written up and published in a blog post.

Implementation steps:

  • do user testing with up to ten volunteer subjects, taking notes
  • write and publish blog post about results

Time estimate: 10 days

Deliverable: blog post describing user testing results

Milestone: acceptance_revision

When this milestone has been reached: The acceptance criteria document has been revised based on feedback from stakeholders.

Implementation steps:

  • review acceptance criteria against results of user testing and stakeholder interviews
  • update acceptance criteria to match results
  • write and publish blog post describing changes to acceptance criteria

Time estimate: 5 days

Deliverable: blog post describing changes to acceptance criteria

DONE: Milestone: gpg_comparison

When this milestone has been reached: The functionality in gpg has been compared with that of sq, and anything that’s missing from sq, and deemed needed by many people, has been documented as issues in the Sequoia issue tracker. A summary of the results has been published in a blog post.

Implementation steps:

  • compare gpg’s manual page against sq’s documentation, making notes of what sq already implements and what it is missing
  • compile list of detailed gpg functionality and comparisons with sq
  • open issues for missing important features
  • write and publish blog post describing missing sq functionality

Time estimate: 5 days

Deliverable: blog post describing missing sq functionality

Milestone: missing_features

When this milestone has been reached: As much as possible of the functionality missing from sq, compared to gpg, has been implemented, with time constraints. The changes have landed in the main line of development of sq. Related acceptance criteria have been documented and are verified in Sequoia CI.

This a milestone that has a fairly high risk of scope explosion. This will be mitigated using time boxing as described above.

Implementation steps:

  • plan implementation of missing features
  • implement as much as I have of what is missing, including verification scenarios
  • time box to avoid spending infinite time on this
  • write and publish a blog post describing added functionality

Time estimate: 20 days

Deliverable: blog post describing added functionality

DONE: Milestone: json_api_sketch

When this milestone has been reached: A sketch for how the first iteration of the sq JSON API would work has been written and published.

This may cover only a subset of the functionality, but will cover enough to be useful for real use. This is purely a document, not actual code, but will lay the foundation for how the initial version of the JSON API will work and what it will look like. However, the API may well change when subjected to real use, and so nothing is set in stone at this stage. The initial sketch is meant to get us started.

Implementation steps:

  • pick the sq commands most likely to need JSON output support
  • sketch what the JSON output might be like for each
  • write and publish blog post with sketch of initial JSON API

Time estimate: 5 days

Deliverable: blog post with sketch of JSON API

Milestone: json_api_draft_1

When this milestone has been reached: A first prototype of the sq JSON API has been implemented. This will be functional and its acceptance criteria will be documented and verified. This implementation will be used for user testing of the JSON API and to gather feedback from stakeholders.

Implementation steps:

  • implement the JSON API sketch, including adding acceptance criteria and verification scenarios for new functionality
  • write and publish blog post describing new features

Time estimate: 10 days

Deliverable: blog post describing new features

Milestone: json_api_user_test

When this milestone has been reached: The sq JSON API has been user tested by observing people use it to achieve specific goals. The observations have been written up and published in a blog post.

Implementation steps:

  • the JSON API user tests have been done with up to ten volunteers, with notes taken, up to an hour per person
  • write and publish blog post of results

Time estimate: 10 days

Deliverable: blog post describing user testing results

Milestone: json_api_feedback

When this milestone has been reached: Feedback from user testing and stakeholder interviews about JSON API has been processed, written up, and published. This will include a plan for any changes to make to the API.

Implementation steps:

  • analyze the user testing results and stakeholder interviews regarding the JSON API
  • plan what needs to be changed
  • write and publish blog post about the findings

Time estimate: 5 days

Deliverable: blog post describing feedback on JSON API

Milestone: json_api_implementation

When this milestone has been reached: The sq JSON API implementation has been revised based on feedback from stakeholders and user testing. Acceptance criteria and their verification have been updated as well. The changes have been merged to the main line of Sequoia development.

This is another milestone that has a fairly high risk of scope explosion. Mitigation using time boxing.

Implementation steps:

  • change JSON API based on feedback from stakeholders and user testing
  • write and publish blog post describing changes made

Time estimate: 10 days

Deliverable: blog post about sq JSON API changes

Milestone: acceptance

When this milestone has been reached: All sq acceptance criteria have been documented and their verification added to Sequoia CI. The document has been published. This will include acceptance criteria for all the new functionality implemented in the project.

Implementation steps:

  • tidy up what’s been done in prior milestones
  • write and publish blog post describing how sq acceptance criteria are handled

Time estimate: 1 day

Deliverable: blog post about sq acceptance testing

Milestone: functionality

When this milestone has been reached: sq is now considered fully functional for the purposes of the project. Any known missing functionality has been documented in the Sequoia issue tracker.

Implementation steps:

  • tidy up what’s been done in prior milestones
  • write and publish blog post about all the new functionality added to sq in this project

Time estimate: 1 day

Deliverable: blog post about new sq functionality

Milestone: json_api

When this milestone has been reached: The JSON API of sq has been implemented and the changes have been merged into the main line of sq development. The acceptance criteria for the JSON API have been documented. Any known missing functionality has been documented in the Sequoia issue tracker.

Implementation steps:

  • tidy up what’s been done in prior milestones
  • write and publish blog post describing new JSON API as whole

Time estimate: 1 day

Deliverable: blog post about sq acceptance testing

Milestone: nlnet_proposal

When this milestone has been reached: The project proposed to NLnet is now finished, all payments have been received, a final blog post about the project has been published, and the project is wrapped up.

Implementation steps:

  • tidy up what’s been done in prior milestones
  • write and publish blog post about the project as whole, with a summary of what has been done and what was postponed

Time estimate: 1 day

Deliverable: blog post about project