I’ve decided to write my own Markdown script,
possibly for dubious reasons.

I’m getting antsy to code.

But before I get started on the testing and implementation, I need to:

  • write the requirements
  • write a simple stub implementation
  • write a testing strategy
  • explore test frameworks

Then, FINALLY, I can start testing and implementing.
I will talk about the term ‘testing and implementing’ in a future post.

Let’s take a look at the requirements.

Requirements for Markdown

Structure

  1. Written in Python
  2. Use only python packages and libraries that come with a relatively standard python installation.
  3. All contained in one python file

Functionality

  1. Implement all original Markdown functionality.

That’s it for now.

Discussion

First off, this set of requirements might seem kind of lame.
There’s not much there.

However, I think it’s enough to get started.
I don’t want to spend tons of time writing the requirements because I know
lots of the nitty gritty detail requirements should be represented as
functional tests. And I think writing them at the time I’m writing the
functional tests is the right way to go.

S.1. Written in Python

This is in here for a few reasons.

  1. Since my test code is written in python, and this blog is focused on testing
    with python, I’d like the project to contain code samples in python.
    Mostly just to not confuse the issue by adding an extra language as a
    requirement for reading this site.

  2. I want a version of Markdown in Python for my own use. One that I can
    extend to meet my own needs.

  3. I want to show examples of how you can use python testing frameworks for
    functional testing, regardless of whether or not your target language is also python.
    Functional testing encompasses system level testing, acceptance testing,
    regression testing, and more.
    But it does NOT include unit testing.
    Unit testing is a beast unto itself. Lots of writing exists already for this
    topic. I don’t plan on adding to that pile.
    I’m going to focus on functional tests.

I am only going to test the code via the external interfaces.
I am going to write about this decision more in a future post.

S.2. Use only python packages and libraries that come with a relatively standard python installation.

This requirement is here because I want a user of the script to be able to download it and run it just
about anywhere without having to instally any prerequiesite packages.
This is one of the beautiful features of the original markdown.pl script.
I want to keep that simplicity of usage.

What is a ‘relatively standard python installation’?
As a whole, I have no idea.
But for me, I will be testing on:

  • the python that came pre-installed on my mac, running mountain lion.
  • the python I have running on a ubuntu linux laptop.

Eventually, I may put some strict version numbers around this requirement.
For now, I’m just going to try to not use any packages that I have to download from anywhere.
And let any users of the script gripe at me if I violate this requirement on some specific platform.

S.3. All contained in one python file

This requirement is in here for the same reason as S.2.
The original markdown.pl found at daring fireball is one file.
A user just needs to know how to run a perl script on a command line to use it.
You don’t have to install it as a site package or anything.
Pretty cool.
I want to keep that feature.

F.1. Implement all original Markdown functionality.

Well, this seems pretty obvious.
Specifically, I’m not going to implement any extensions to the syntax
(such as MultiMarkdown, MarkdownExtra, or GFM) in the first version.

I may expand on this requirement to re-state the syntax.
However, I may also just leave that to the test cases to document.
I haven’t decided yet.
I don’t think it’s necessary to decide right now.

This is also a reasonable example of a requirement that developers face in the real world.
It is kind of vague, and will need some research and detail added to it as development progresses.

That’s it

That’s it for requirements for now.

Requirements change over time.
And I see no reason why that won’t be the case for this project.
Therefore, a requirements document is the first thing I will be adding to version control.

Yep. The requirements themselves should be the first artifact tracked in version control for a project.

Next, a stub

Well, I better get coding.