A software development project is a collaborative endeavor. Several team members work together and produce artifacts that evolve continuously over time, a process that Alberto Brandolini (@ziobrando) calls Collaborative Construction. Regularly, these artifacts are taken in their current state and transformed into something that become a release. Typically, source code is compiled and packaged into some executable.
The idea of Collaborative Artifacts as Code is to acknowledge this collaborative construction phase and push it one step further, by promoting as many collaborative artifacts as possible into plain text files stored in the same source control, while everything else is generated, rendered and archived by the software factory.
Collaborative artifacts are the artifacts the team works on and maintains over time thanks to the changes done by several people through a source control management such as SVN, TFS or Git, with all their benefits like branching and versioning.
Keep together what varies together
The usual way of storing documentation is to put MS Office documents into a shared drive somewhere, or to write random stuff in a wiki that is hardly organized.
Either way, this documentation will quickly get out of sync because the code is continuously changing, independently of the documents stored somewhere else, and as you know, “Out of sight, out of mind”.
we now have better alternatives
We now have better alternatives
Over the last few years, there has been changes in software development. Github has popularized the README.md overview file written in Markdown. DevOps brought the principle of Infrastructure as Code. The BDD approach introduced the idea of text scenarios as a living documentation and an alternative for both specifications and acceptance tests. New ways of planning what a piece of software is supposed to be doing have appeared as in Impact Mapping.
All this suggests that we could replace many informal documents by their more structured alternatives, and we could have all these files collocated within the source control together with the source.
In any given branch in the source control we would then have something like this:
Source code (C#, Java, VB.Net, VB, C++)
Basic documentation through plain README.md and perhaps other .md files wherever useful to give a high-level overview on the code
SQL code as source code too, or through Liquibase-style configuration
Living Documentation: unit tests and BDD scenarios (SpecFlow/Cucumber/JBehave feature files) as living documentation
Impact Maps (and every other mindmaps), may be done as text then rendered via tools like text2mindmap
Any other kind of diagrams (UML or general purpose graphs) ideally be defined in plain text format, then rendered through tools (Graphviz, yUml).
Dependencies declarations as manifest instead of documentation on how to setup and build manually (Maven, Nuget…)
Deployment code as scripts or Puppet manifests for automated deployment instead of documentation on how to deploy manually
Plain Text Obsession is a good thing!
Nobody creates software by editing directly the executable binary that the users actually run at the end, yet it is common to directly edit the MS Word document that will be shipped in a release.
Collaborative Artifacts as Code suggests that every collaborative artifact should be text-based to work nicely with source control, and to be easy to compare and merge between versions.
Text-based formats shall be preferred whenever possible, e.g. .csv over xls, rtf or .html over .doc, otherwise the usual big PPT files must go to another dedicated wiki where they can be safely forgotten and become instantly deprecated…
Like a wiki, but generated and read-only
My colleague Thomas Pierrain summed up the benefits of this approach, for a documentation:
always be up-to-date and versioned
easily diff-able (text filesn e.g. with Markdown format)
respect the DRY principle (with the SCM as its golden source)
easily browsable by everyone (DEV, QA, BA, Support teams…) in the readonly and readable wiki-like web site
easily modifiable by team members in a well know and official location (as easy as creating or modifying a text file in a SCM)
What’s next?
This approach is nothing really new (think about LateX…), and many of the tools we need for it already exist (Markdown renderers, web site to organize and display Gherkin scenarios…). However I have never seen this approach fully done in an actual project. Maybe your project is already doing that? please share your feedback!
Following my ongoing work on a theory of rhythms and a corresponding physical instrument using lasers, here is a version of the same idea implemented into an Arduino: a generative sequencer. The idea is to generate rhythms, and perhaps melodies, from one rhythm seed, then use mutated copies of it to create something more interesting, all this in realtime using knobs and buttons.
This is not ‘yet another step sequencer’, but really a generative music device, that builds a real time MIDI loop based on an underlying theory described in a previous post.
This is work in progress, and is shown ‘as is’ for the sake of getting feedback.
Approach
The approach is to generate a “seed” of rhythm that is then copied a few times into “instances”, each instance being distorted in its own way. The controls for the human player (or programmer) are therefore all about adjusting the deformations (transforms actually) to apply to each instance, and of course defining the seed.
Eventually each instance is wired to a MIDI note, channel etc. to remote control a synthesizer or a drum machine or any MIDI setup, to generate actual sounds.
Principle: one seed, many transformed instances
The maths
Given a seed of rhythm of lengh length composed of pulses, each of duration m, then:
for each instance k of the seed, each pulse i,
pulse(k, i) happen at time t = phase(k) + i . m . stretch(k), t < length
where phase(k) and stretch(k) are the phase and stretch settings for the instance k.
Realtime control of the sequencer is therefore all about setting the phase and stretch values for each instance, once the pulse number and the pulse duration of the seed have been globally set.
Inversely, for a given instance k, at time t, we have a pulse if:
there exists an i, such as t = phase(k) + i * m * stretch(k)
i.e. i = (t - phase(k))/(m * stretch(k))
Thinking in MIDI ticks (24 per quarters), in 4/4, for 1 bar, length = 4 * 24, phase is in [-24 .. 24] and stretch is in [4:1 .. 1:4] and m in [12 .. 48] by steps of 12 ticks.
The implementation is the very simple: for each instance of the seed, and given its phase and stretch settings, whenever the modulo condition above is true, then we emit its MIDI note, with the set velocity on the set MIDI channel.
As usual, the pace of the loop is primarily based on the value from the Tempo potentiometer.
Overview of the circuit, with the switches and the knobs
Adding some swing
8th note swing
The EMU SP-1200, early Linn machines, Roland 909, Akai MPC and many other machines are famous for their swing quantize, a feature that delays every other note by a certain amount in order to create a groovy feeling (see Swung Note).
Different machines express the swing factor in different ways, we will stick to the MPC format, expressed in percent from 50% (no swing, play straight) to 75% (hard shuffle).
For a swing for 8th notes, this swing factor represents the ratio of the period of the first 8th note over the period of the second 8th note, in percent.
In the Arduino code of our generative sequencer, we chose to do a fixed swing for 8th notes only.
A big constraint is that we are limited to a resolution of 24 ticks per quarter note, which is not a lot! By contrast, MPC have a 96 ppq resolution. Because a hard swing of 70% translates into hardly 2 MIDI ticks at 24 ppq, doing the swing on top of the ticks will not be accurate at all!
The only solution is to vary the internal tempo before and after each 8th note. The drawback (or advantage) is that the MIDI clock being sent will also move, reflecting the same swing. Since the Swing knob value is actually between 0 and 25 (to be read from50% to 75%), the tempo before (t-) and the tempo after (t+), are given by:
t+/- = (50 +/- swing) * t / 50
where t is the base loop period without swing
Video Demo
Here is a video demo. There are only 3 instances, selected by the switches 1, 2 and 3; the first switch selects the GLOBAL settings: step duration (quarter, 8th etc.), swing factor, tempo. Each instance can be set its Phase, Stretch, MIDI note, velocity and MIDI channel. Here I have preset the MIDI channels, instance 1 on channel 1 (the microKorg) and instances 2 and 3 on channel 2 (the MPC with a drum kit).
The goal is to build a simple beat by only adjusting the parameters.
Please note that some parts of the code are not used any more, such as the big constant arrays, and some comments are not up to date (e-g no prime number anymore).
All analog inputs are wired to simple knobs. Digital inputs 8, 9, 10 , 11 are the four buttons used to switch pages. Digital output 12 is the activity LED (showing when the knob is active within the knob pagination). MIDI out is on the Tx pin.
/*
* Generative rhythm sequencer, more details at: http://cyrille.martraire.com
*
* Knob mapping according to a grid 2^n . prime^m, against the MIDI 24 ticks/quarter.
*
* Knob pagination to multiplex the knobs several times with LED to show activity.
*
* Memory-less event handling thanks to maths relationships.
*
* MIDI note on output on every 16 channel and MIDI clock according to tempo.
//---------- USER INPUT AND PAGINATION -----------
#define PAGE_NB 4
#define KNOB_NB 6
#define FIRST_PAGE_BUTTON 8
#define PROTECTED -1
#define ACTIVE 1
#define SYNC_LED 12
// the permanent storage of every value for every page, used by the actual music code
int pageValues[PAGE_NB][KNOB_NB];
// last read knob values
int knobsValues[KNOB_NB];
// knobs state (protected, enable...)
int knobsStates[KNOB_NB];
// current (temp) value just read
int value = 0;
// the current page id of values being edited
int currentPage = 0;
// signals the page change
boolean pageChange = false;
//temp variable to detect when the knob's value matches the stored value
boolean inSync = false;
int maxValue = 890;
int scaleLen = 15;
int *scale = scale3;
int step = 60;
int center = 30;
int coeff = 10;
//---------- GENERATIVE MUSIC CODE ---------
unsigned int cursor = 0;
int bars = 1;
int length = bars * 4 * 24;
// INPUTS
int PHASE = 0;
int STRETCH = 1;
//int DIRECTION = 2;
int NOTE = 2;
int DURATION = 3;
int VELOCITY = 4;
int CHANNEL = 5;
// GLOBAL KNOBS (seed and global settings)
int seedDuration = 24;
int seedTimes = 8;
int instanceNb = 4;
int swing = 0;//0..25% (on top of 50%)
//
int loopPeriod = 125/6;//120BPM
int actualPeriod = loopPeriod;
//instance i
int phase = 0;
int stretch = 1;
int note = 48;
int duration = 24;
int velocity = 100;
int channel = 1;
// custom map function, with min value always 0, and out max cannot be exceeded
long mapC(long x, long in_max, long out_min, long out_max)
{
if (x > in_max) {
return out_max;
}
return x * (out_max - out_min) / in_max + out_min;
}
// for each instance, and for the given cursor, is there a pulse?
boolean isPulse(byte phase, byte stretch){
int num = cursor - phase;
int denum = seedDuration * stretch / 4;
return num % denum == 0;
}
// Sends a MIDI tick (expected to be 24 ticks per quarter)
void midiClock(){
Serial.print(0xF8, BYTE);
}
// plays a MIDI note for one MIDI channel. Does not check that
// channel is less than 15, or that data values are less than 127:
void noteOn(char channel, char noteNb, char velo) {
midiOut(0x90 | channel, noteNb, velo);
}
// plays a MIDI message Status, Data1, Data2, no check
void midiOut(char cmd, char data1, char data2) {
Serial.print(cmd, BYTE);
Serial.print(data1, BYTE);
Serial.print(data2, BYTE);
}
// read knobs and digital switches and handle pagination
void poolInputWithPagination(){
// read page selection buttons
for(int i = FIRST_PAGE_BUTTON;i < FIRST_PAGE_BUTTON + PAGE_NB; i++){
value = digitalRead(i);
if(value == LOW){
pageChange = true;
currentPage = i - FIRST_PAGE_BUTTON;
}
}
// if page has changed then protect knobs (unfrequent)
if(pageChange){
pageChange = false;
digitalWrite(SYNC_LED, LOW);
for(int i=0; i < KNOB_NB; i++){
knobsStates[i] = PROTECTED;
}
}
// read knobs values, show sync with the LED, enable knob when it matches the stored value
for(int i = 0;i < KNOB_NB; i++){
value = analogRead(i);
inSync = abs(value - pageValues[currentPage][i]) < 20;
// enable knob when it matches the stored value
if(inSync){
knobsStates[i] = ACTIVE;
}
// if knob is moving, show if it's active or not
if(abs(value - knobsValues[i]) > 5){
// if knob is active, blink LED
if(knobsStates[i] == ACTIVE){
digitalWrite(SYNC_LED, HIGH);
} else {
digitalWrite(SYNC_LED, LOW);
}
}
knobsValues[i] = value;
// if enabled then miror the real time knob value
if(knobsStates[i] == ACTIVE){
pageValues[currentPage][i] = value;
}
}
}
