Read this article about Puzzle Driven Development. Check also patent application US 12/840,306
Also, check 0pdd.com: a hosted service, where this command line tool works for you. Read this first: PDD in Action.
Install it first:
$ gem install pdd
Run it locally and read its output:
$ pdd --help
You can exclude certain files from the search, for example:
pdd --exclude=src/**/*.java --exclude=target/**/*
pdd --exclude=src/**/*.java # exclude .java files in src/
pdd --exclude=src/**/* # exclude all files in src/
Every puzzle has to be formatted like this (pay attention to the leading space in every consecutive line):
/**
* @todo #[issue#]<:[time]></[role]> <[description]>
*/
[related code]
[] - Replace with apropriate data (see text enclosed in brackets) <> - Omitable (enclosed data can be left out)
Example:
/**
* @todo #234:15m/DEV This is something to do later
* in one of the next releases. I can't figure out
* how to implement it now, that's why the puzzle.
*/
void sendEmail() {
throw new UnsupportedOperationException();
}
If you use it in combination with 0pdd, after processing this text, the issue titled "File.java:10-13: This is something to do later in one of ..." will be created. The specified markers will be included in the issues body along with some predefined text. If your comment is longer than 40 characters, it will be truncated in the title.
It starts with @todo
, followed by a space and a mandatory puzzle marker.
Possible formats of puzzle markers (it doesn't matter what the
line starts with and where it is located,
as long as you have that @todo
right in front
of the mandatory marker):
// @todo #224
/* @todo #TEST-13 */
# @todo #55:45min
@todo #67/DES
;; @todo #678:40m/DEV
Here DES
and DEV
are the roles of people who must fix that puzzles;
45min
and 40m
is the amount of time the puzzle should take;
224
, TEST-13
, 55
, 67
, and 678
are the IDs of the tickets these
puzzles are coming from.
Markers are absolutely necessary for all puzzles, because they allow
us to build a hierarchical dependency tree of all puzzles, like
this one,
for example. Technically, of course, you can abuse the system
and put a dummy #1
marker everywhere.
You can specify post-parsing rules for your puzzles, in command line, for example:
$ pdd --rule=min-estimate:60 --rule=max-estimate:120
These two parameters will add two post-parsing rules min-estimate
and max-estimate
with parameters. Each rule may have an optional
parameter specified after a colon.
Here is a list of rules available now:
-
min-estimate:15
blocks all puzzles that don't have an estimate or their estimates are less than 15 minutes. -
max-estimate:120
blocks all puzzles with estimates over 120 minutes. -
available-roles:DEV,IMP,DES
specifies a list of roles that are allowed in puzzles. Puzzles without explicitly specified roles will be rejected. -
min-words:5
blocks puzzles with descriptions shorter than five words. -
max-duplicates:1
blocks more than one duplicate of any puzzle. This rule is used by default and you can't configure it at the moment, it must always be set to1
.
You can put all command line options into .pdd
file. The options from the
file will be used first. Command line options may be added on top of them.
See, how it is done in yegor256/0pdd.
The XML produced will look approximately like this (here is a real example):
<puzzles>
<puzzle>
<ticket>516</ticket>
<estimate>15</estimate>
<role>DEV</role>
<id>516-ffc97ad1</id>
<lines>61-63</lines>
<body>This has to be fixed later...</body>
<file>src/test/java/org/takes/SomeTest.java</file>
<author>Yegor Bugayenko</author>
<email>[email protected]</email>
<time>2018-01-01T21:09:03Z</time>
</puzzle>
</puzzles>
XSD Schema is here. The most interesting parts of each puzzle are:
-
ticket
is a ticket name puzzle marker starts from, in most cases it will be the number of GitHub issue. -
estimate
is the amount of minutes the puzzle is supposed to take. -
id
is a unique ID of the puzzle. It is calculated by the internal algorithm that takes into account only the text of the puzzle. Thus, if you move the puzzle from one file to another, the ID won't change. Also, changing the location of a puzzle inside a file won't change its ID. -
lines
is where the puzzle is found, inside the file.
Read these guidelines. Make sure you build is green before you contribute your pull request. You will need to have Ruby 2.3+ and Bundler installed. Then:
$ bundle update
$ bundle exec rake
If it's clean and you don't see any error messages, submit your pull request.
This is how you run the tool locally to test how it works:
$ ./bin/pdd --help