@todo #31 to add some badge which will show the
Puzzle Driven Development concept,
0pdd tools belong to Yegor Bugayenko.
@puzzlerbot is a bot which provides new ways of managing the
puzzles - trackable TODO stub-like tasks which make possible to
in fast and smooth way. Initial concept supposes that the puzzles
are defined as specially-formatted TODO items in the project's source code, but
practically this approach has some drawbacks:
Code base is volatile. Puzzles in the code rarely stay in one line. Some code is added, some code is removed, some codebase is changed intentionally or during merge conflicts resolving - it all means that puzzle in code has no stable identity. It opens plenty of ways to mess the issue tracker or get abnormal behavior of the parsers.
Code is not the only place where we could cut corners: we may want to cut corners during various high-level discussions, architecture planning, epic stories decomposition - somewhere where code is not existing yet.
The syntax, used by documentation generators (like javadoc, for example) differs from conventions, used in GitHub (Markdown). It makes the puzzle hard, almost impossible, to format properly both in documentation and in GitHub Markdown.
@puzzlerbot's approach is to scan for puzzles in issues or pull requests comments after
the issue or pull request is closed. Comments tend to be more stable than
the code base, they may exist when even no code is written yet, and they are rarely changed.
@puzzlerbotis not a replacement for
0pdd. It will be always possible to use them both in one project without conflicts.
Puzzlerbot supports GitHub and GitLab integration.
Just add new GitHub webhook to your project's "Settings" -> "Webhooks" tab:
- Payload URL:
- Which events would you like to trigger this webhook:
Pull requestswould be enough.
In your GitLab project's "Settings" -> "Integration" view, add new webhook:
- Payload URL:
Merge requests eventswould be enough.
Note that you can also deploy your own private and personal
@puzzlerbot instance using
How to create a puzzle
Puzzles are placed in issue or pull request comments. Once the issue or pull request is
@puzzlerbot scans its comments for puzzles and creates one issue per puzzle.
One comment may have at most one puzzle. To make
@puzzlebot properly recognize your puzzles,
follow conventions described in this section.
Consider comment with this text:
@puzzlebot FYI Something weird happened with the system, heeds to be fixed. Steps to reproduce: 0. Preconditions 1. Step one 2. Step two 3. Step three Expected result: Everything is okay. Actual result Exception is thrown.
This comment will be parsed by
@puzzlerbot as a puzzle with title
"Something weird happened with the system, heeds to be fixed." and description
"Steps to reproduce..." etc.
When parsing comments and seeking for puzzles,
@puzzlerbot splits each comment to
paragraphs and classifies each paragraph to one of the types below:
Controlling - the paragraph which mentions
@puzzlerbotuser. Controlling paragraphs are an indicator that the comment represents a puzzle. One comment may have any number of controlling paragraphs but only the first will be taken into account. Controlling paragraphs are not included to the resulting issue.
Title - the first non-controlling paragraph in a comment. One comment may have only one title paragraph. This paragraph is used for the issue's title.
Description - rest of the paragraphs. They are used as the issue's description.
Copyright (c) 2018 Kapralov Sergey
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.