draft suggestion for recording Requirements

Refactor the project structure in order to capture requirements as executable acceptance tests, so that anyone volunteering to work on memstate can know the status of what features have been built, and are currently available to use and work (based on the current release).

• requirements should be written at a high enough level describing the required benefits that the feature should deliver, and not describe the how, so that if we change the specific implementation the test should as far as possible not require much changing.

• requirements for any feature that a dev is going to work on should be written before any code is written. (so that we can make sure the requirements are clear and fully understood.)

• Suggestion : requirements can be attached to the issue or project board and recorded in Gherkin syntax, see example below

• be written as BDD style acceptance tests so that we can run the tests as part of CICD.

• acceptance tests should contain sufficient examples that anyone new can easily see the intention of the feature.

• the final acceptance test that is written should show the simplest code possible that proves that the system behaves as the documentation describes. (see example at the bottom) This is really to prove to a user that the behaviour works. The real proof for us, will be done through a complete set of unit, integration, performance, load and security tests. These tests will cover a wide set of edge cases that are not necessary to include in the acceptance tests

• the acceptance tests should use as few Mocks as possible to simulate as far as possible the actual code that a user could put together in a simple console application. (so that the tests can serve as valuable and real how-to code examples.)

• there will be some minor duplication between work on the requirements and the documentation. The difference between the 'docs' and 'requirements' is that the docs and getting started focuses on a slice through memstate and covers only the basics. Requirements are written 'per feature', every time someone extends memstate with new functionality. If a new piece of functionality is something that a user needs to be aware of from the very beginning of using memstate then we'd update the documentation at the same time.

sample feature expressed in Gherkin

# sample `feature` text notes for a feature, saved in the  github project or issue
# this get's translated into a C# test when a developer starts to work on the issue or feature.
# these are written and reviewed *before* development starts. 

Epic : Account/ClosingAccount
Feature : user cannot close account with a negative balance

Given an account with <balance>
when the account is closed()
then the result is <result>

Examples

    balance | result
    --------| ------
    [NULL]  | closed
    0       | closed
    -10     | exception
    10      | closed

acceptance test translated to C#

• in this example, someone pulled a card from the backlog called, "user cannot close account with negative balance". This sample shows that features can have more features (e.g. epics) and can be modified over time, and still keep all the tests and requirements together in one place.
• rough sample below showing suggested folder structure and test naming for epics
• class ClosingAccount would reside in a folder in file /Memstate.Requirements/Account/ClosingAccount.cs
• this convention allows us to have any amount of nesting as appropriate on a case by case basis.

  namespace Memstate.Requirements.Account
{

  // using nested classes for epics to group all the requirements in one place
   public class ClosingAccount
  {
     [TestCase(null)]
     [TestCase(0M)]
     [TestCase(100M)]
      [Test]
       public void user_closing_account_with_positive_zero_or_null_balance_should_close_account(decimal balance)
      {
          var account = new Account(balance);
          var result = account.Close();
          Assert.AreEqual(result, Result.Closed);
      }
 
     [Test]
       public void user_closing_account_with_negative_balance_should_throw_exception()
      {
          var account = new Account(-10M);
         Assert.Throws<Exception>( a=> account.Close());
      }
 
 }

}

Suggestion above based on a gitter discussion where I proposed updating the project to record requirements using the same syntax I use for requirements in my Konsole project here : https://github.com/goblinfactory/konsole/blob/master/Konsole.Tests/WindowTests/SplitTests.cs