Homepage

Having a homepage in the day and age seems a bit archaic but I like it. Maintaining it however is a hassle. So as an exercise I’ve decided to create an SRS for my homepage generation.

../_images/homepage.png

Software Requirements Specification

Version 1.0
Created August 03, 2016
Updated July 21, 2019

Introduction

Purpose

The purpose of this document is to present a detailed description of the homepage project tooling. It will explain the purpose and features of the application, any interfaces that it might have, what it will do and the constraints under which it must operate.

Scope

The homepage project tooling will help maintain “vanzantvoort.org”. It must be designed such that:

  • a change can be reviewed local before publishing
  • unnecessary traffic whilst publishing is avoided
  • the actions needed for the author are kept to a minimum

System Environment

The “vanzantvoort.org” site content is built from a number of sources:

  • articles and pages in the source
  • social media
  • static albums

Updates result in change numbers used to track versions in the content. Versions are used publish content updates.

References

To Be Defined

Definitions

CI
Continuous Integration
development host
A (virtual) host used to host the intermediate results.
Term Definition
CI Continuous Integration
development host A (virtual) host used to host the intermediate results.

Use Cases

The regular template of the use cases is:

Use case number – Use case name
Summary A short description of the use case
Rationale Why is this needed
Roles What user definitions are involved [1]
Precondition State of the software before
Process Steps in the use case
Result State of the software after

Note

Parts can be omitted if not applicable or overly obvious.

UC description
UC-01 UC-01 - add an article
UC-02 UC-02 - update an article
UC-03 UC-03 - post a tweet
UC-04 UC-04 - upload a new image
UC-05 UC-05 - publish a new version of the site

UC-01 - add an article

Summary

An article is added to the site.

Process
  • The command “page -a <article path>” is executed to add the new article
  • an editor is opened to edit the article.
  • the results are viewed on the development server
Result
  • The article is viewable on the development server
  • The change log is updated
  • The version of vanzantvoort.org is updated

UC-02 - update an article

Summary

Update an existing article.

Precondition

The article exists

Process
  • The command “page -u <article path>” is executed to update the existing article
  • an editor is opened to edit the article.
  • the results are viewed on the development server
Result
  • The updated article is viewable on the development server
  • The change log is updated
  • The version of vanzantvoort.org is updated

UC-03 - post a tweet

Summary

Once a configured social media source is updated the website sources will be updated.

Note

given the low frequence of the updates the polling intervals are going to be low (e.g. daily).

Rationale

External sources of information should automatically be included.

Precondition

The interface to these external sources is available and configured.

Process
  • The command “page –update-sources” is run periodically.
  • If new content is available the command “page –publish=dev” is run automatically .
Result
  • The change log is updated
  • The version of vanzantvoort.org is updated

UC-04 - upload a new image

Summary

A new image is placed in the archive.

Rationale

Content can be added.

Precondition

The album management application is available and configured as an external interface.

Process
  • Target is copied to the archive
  • (optionally) target meta data is updated
  • The command “page –update-albums” is run periodically.
  • If new content is available: * the album is updated * the command “page –publish=dev” is run automatically.
Result
  • The change log is updated
  • The version of vanzantvoort.org is updated

UC-05 - publish a new version of the site

Summary

A new version of the site is ready to be published. Only the updated content is uploaded or removed.

Precondition
  • A hosted site and exported sources are available.
  • The tools for the updating the content are available and configured correctly.
Process
  • A version is deemed as production
    • “page –version <number> –status=prod” is executed.
  • The content is published
    • “page –publish=prod” is executed to
      • the version is obtained from the production site.
      • the version of the production site is compared to the version submitted.
      • a work list of transactions is created from the difference.
      • each transaction is executed separately
Result
  • production site is updated to match the content of version “<version>” of the archive.

Functional requirements

FR description
FR-01 `FR-01 - the application must provide template content for new articles`_
FR-02 FR-02 - the application will not overwrite existsing articles
FR-03 FR-03 - the application will maintain a changelog
FR-04 `FR-04 - the application must maintain a version for the archive`_
FR-05 FR-05 - the application must maintain multiple versions of the same export
FR-06 FR-06 - the application must be able to create a delta between two versions of the archive
FR-07 FR-07 - interfaces must be available to obtain external source content
FR-08 FR-08 - interfaces must be available to publish the archive to different destinations
FR-09 FR-09 - the application must be able to obtain version information about published and archived content
FR-10 FR-10 - interfaces must be available to access external renderers

FR-01 - the application will provide template content for new articles

Summary

Upon creation of new a new articles a template document must be provided.

Rationale
  • consistency
  • speed
Requirements

When a new article is created a template document is copied to it.

The page application will provide a default template unless this value is overridden by –template=<template>.

FR-02 - the application will not overwrite existsing articles

Summary

If a target exists it cannot be created.

Rationale

When updating or creating an article the original content cannot result in existing content being replaced by blanc content.

Requirements

If “page -a <article path>” is executed on an existing article the application exits with an error message.

FR-03 - the application will maintain a changelog

Summary

The application will maintain a change log.

Rationale

The change log will be used to determine version differences and whether or not a publish step is needed. It also provided a reference.

Requirements

When any action is taken all relevant data (save for the content of the actual objects) is stored in this change log file.

FR-04 - the application will maintain a version for the archive

Summary

To track the state of “vanzantvoort.org” a version will be maintained in the export.

Rationale

The version is a reference with which the site content is maintained.

Completely replacing all the content on “vanzantvoort.org” for every minute step is very inefficient and tools like rsync do not work (well) with ftp.

Requirements

To Be Defined

FR-05 - the application must maintain multiple versions of the same export

Summary

To Be Defined

Rationale

To Be Defined

Requirements

To Be Defined

References

To Be Defined

FR-06 - the application must be able to create a delta between two versions of the archive

Summary

To Be Defined

Rationale

To Be Defined

Requirements

To Be Defined

References

To Be Defined

FR-07 - interfaces must be available to obtain external source content

Summary

To Be Defined

Rationale

To Be Defined

Requirements

To Be Defined

References

To Be Defined

FR-08 - interfaces must be available to publish the archive to different destinations

Summary

To Be Defined

Rationale

To Be Defined

Requirements

To Be Defined

References

To Be Defined

FR-09 - the application must be able to obtain version information about published and archived content

Summary

To Be Defined

Rationale

To Be Defined

Requirements

To Be Defined

References

To Be Defined

FR-10 - interfaces must be available to access external renderers

Summary

To Be Defined

Rationale

To Be Defined

Requirements

To Be Defined

References

To Be Defined

Nonfunctional requirements

To Be Defined

[1]To avoid sounding schizophrenic the various roles have been omitted.