{"id":15470424,"url":"https://github.com/skapral/puzzlerbot","last_synced_at":"2025-07-11T03:35:34.531Z","repository":{"id":48668587,"uuid":"134487043","full_name":"skapral/puzzlerbot","owner":"skapral","description":"PDD manager which manages puzzles in issue/PR comments","archived":false,"fork":false,"pushed_at":"2021-07-15T02:24:10.000Z","size":375,"stargazers_count":21,"open_issues_count":21,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-22T12:08:11.771Z","etag":null,"topics":["github","gitlab","grizzly","java","jax-rs","jersey","oo-atom","pdd-puzzles"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skapral.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-22T23:34:56.000Z","updated_at":"2022-01-08T09:01:22.000Z","dependencies_parsed_at":"2022-08-27T04:21:14.920Z","dependency_job_id":null,"html_url":"https://github.com/skapral/puzzlerbot","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/skapral/puzzlerbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skapral%2Fpuzzlerbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skapral%2Fpuzzlerbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skapral%2Fpuzzlerbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skapral%2Fpuzzlerbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skapral","download_url":"https://codeload.github.com/skapral/puzzlerbot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skapral%2Fpuzzlerbot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264527036,"owners_count":23623201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","gitlab","grizzly","java","jax-rs","jersey","oo-atom","pdd-puzzles"],"created_at":"2024-10-02T02:04:38.408Z","updated_at":"2025-07-11T03:35:34.158Z","avatar_url":"https://github.com/skapral.png","language":"Java","readme":"# Puzzler bot\n\n[![Build Status (Travis)](https://img.shields.io/travis/skapral/puzzlerbot/master.svg)](https://travis-ci.org/skapral/puzzlerbot)\n[![Build status (AppVeyor)](https://ci.appveyor.com/api/projects/status/1mwgh02plynasibk/branch/master?svg=true)](https://ci.appveyor.com/project/skapral/puzzlerbot/branch/master)\n[![Codecov](https://codecov.io/gh/skapral/puzzlerbot/branch/master/graph/badge.svg)](https://codecov.io/gh/skapral/puzzlerbot)\n\n## Notice:\n\nPuzzle Driven Development concept, `pdd` and `0pdd` tools belong to [Yegor Bugayenko](yegor256.com).\nLinks:\n- [Puzzle Driven Development concept](https://www.yegor256.com/2010/03/04/pdd.html)\n- [0pdd](https://github.com/yegor256/0pdd/)\n- [pdd](https://github.com/yegor256/pdd/)\n\n## Introduction:\n\n`@puzzlerbot` is a bot which provides new ways of managing the\npuzzles - trackable TODO stub-like tasks which make possible to \n[cut corners](https://www.yegor256.com/2015/01/15/how-to-cut-corners.html)\nin fast and smooth way. Initial concept supposes that the puzzles\nare defined as specially-formatted TODO items in the project's source code, but\npractically this approach has some drawbacks:\n\n- Code base is volatile. Puzzles in the code rarely stay in one line. \nSome code is added, some code is removed, some codebase is changed intentionally\nor during merge conflicts resolving - it all means that puzzle in code has no stable \nidentity. It opens plenty of ways to mess the issue tracker or get abnormal behavior\nof the parsers.\n\n- Code is not the only place where we could cut corners: we may want to cut corners\nduring various high-level discussions, architecture planning, \nepic stories decomposition - somewhere where code is not existing yet.\n\n- The syntax, used by documentation generators (like javadoc, for example) differs\nfrom conventions, used in GitHub (Markdown). It makes the puzzle hard, almost impossible,\nto format properly both in documentation and in GitHub Markdown.\n\n`@puzzlerbot`'s approach is to scan for puzzles in issues or pull requests comments after \nthe issue or pull request is closed. Comments tend to be more stable than \nthe code base, they may exist when even no code is written yet, and they are rarely changed.\n\n## Principles:\n\n- `@puzzlerbot` is not a replacement for `0pdd`. It will be always possible to use\nthem both in one project without conflicts.\n\n## Quick setup:\n\nPuzzlerbot supports GitHub and GitLab integration.\n\n### GitHub\n\nJust add new GitHub webhook to your project's \"Settings\" -\u003e \"Webhooks\" tab:\n- Payload URL: `https://puzzler-bot.apps.skapral.com/github`\n- Content-type: `application/json`\n- Which events would you like to trigger this webhook: `Issues` and `Pull requests` would be enough.\n\n### GitLab\n\nIn your GitLab project's \"Settings\" -\u003e \"Integration\" view, add new webhook:\n- Payload URL: `https://puzzler-bot.apps.skapral.com/gitlab`\n- Trigger: `Issues events` and `Merge requests events` would be enough.\n\n### Misc\n\nNote that you can also deploy your own private and personal `@puzzlerbot` instance using \n[this](DEPLOYMENT.md) guide. \n\n## How to create a puzzle\n\nPuzzles are placed in issue or pull request comments. Once the issue or pull request is\nclosed, `@puzzlerbot` scans its comments for puzzles and creates one issue per puzzle. \nOne comment may have at most one puzzle. To make `@puzzlebot` properly recognize your puzzles,\nfollow conventions described in this section.\n\nConsider comment with this text:\n\n```\n@puzzlebot FYI\n\nSomething weird happened with the system, needs to be fixed.\n\nSteps to reproduce:\n0. Preconditions\n1. Step one\n2. Step two\n3. Step three\n\nExpected result: Everything is okay.\nActual result Exception is thrown.\n```\n\nThis comment will be parsed by `@puzzlerbot` as a puzzle with title\n\"Something weird happened with the system, heeds to be fixed.\" and description\n\"Steps to reproduce...\" etc.\n\n### In details\n\nWhen parsing comments and seeking for puzzles, `@puzzlerbot` splits each comment to\nparagraphs and classifies each paragraph to one of the types below:\n\n- *Controlling* - the paragraph which mentions `@puzzlerbot` user. Controlling paragraphs\nare an indicator that the comment represents a puzzle.\nOne comment may have any number of controlling paragraphs but only the first will be taken \ninto account. Controlling paragraphs are not included to the resulting issue.\n\n- *Title* - the first non-controlling paragraph in a comment. One comment may have only one\ntitle paragraph. This paragraph is used for the issue's title.\n\n- *Description* - rest of the paragraphs. They are used as the issue's description.\n\n## License\n\nMIT License\n\nCopyright (c) 2018 Kapralov Sergey\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskapral%2Fpuzzlerbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskapral%2Fpuzzlerbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskapral%2Fpuzzlerbot/lists"}