{"id":18627529,"url":"https://github.com/yugr/gaplan","last_synced_at":"2025-04-11T05:31:42.833Z","repository":{"id":129418829,"uuid":"163445120","full_name":"yugr/gaplan","owner":"yugr","description":"A simple but functional toolset for constructing and analyzing Gaperton's (aka Vlad Balin's) declarative plans","archived":false,"fork":false,"pushed_at":"2022-07-01T20:35:51.000Z","size":301,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-25T09:52:58.372Z","etag":null,"topics":["declarative","pert","pert-diagrams","plan","planning"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/yugr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-28T19:59:19.000Z","updated_at":"2025-03-13T03:15:34.000Z","dependencies_parsed_at":"2023-03-13T11:23:10.380Z","dependency_job_id":null,"html_url":"https://github.com/yugr/gaplan","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yugr%2Fgaplan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yugr%2Fgaplan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yugr%2Fgaplan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yugr%2Fgaplan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yugr","download_url":"https://codeload.github.com/yugr/gaplan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248347478,"owners_count":21088660,"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":["declarative","pert","pert-diagrams","plan","planning"],"created_at":"2024-11-07T04:42:42.598Z","updated_at":"2025-04-11T05:31:42.818Z","avatar_url":"https://github.com/yugr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![License](http://img.shields.io/:license-MIT-blue.svg)](https://github.com/yugr/gaplan/blob/master/LICENSE.txt)\n[![Build Status](https://github.com/yugr/gaplan/actions/workflows/ci.yml/badge.svg)](https://github.com/yugr/gaplan/actions)\n[![Total alerts](https://img.shields.io/lgtm/alerts/g/yugr/gaplan.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/yugr/gaplan/alerts/)\n[![Codecov](https://codecov.io/gh/yugr/gaplan/branch/master/graph/badge.svg)](https://codecov.io/gh/yugr/gaplan)\n\n# What is this?\n\nGaplan is a simple but functional toolset for constructing and\nanalyzing [Gaperton's](http://gaperton.livejournal.com)\n(aka Vlad Balin's) *declarative plans*.\n\nIt supports plan analysis (mainly checking for common mistakes)\nand generation of various artifacts (e.g PERT diagrams,\n[TaskJuggler](http://taskjuggler.org/) plans and burndown charts).\n\nThis is very much a work-in-progress, driven by my own planning needs.\nI'm happy to improve the tool so ping me if you consider using it.\n\n# About declarative planning\n\nDeclarative planning is a goal-based approach to building plans,\nbacked up with an easy-to-use notation for writing them down.\n\nDeclarative plannig can be roughly described as modelling projects\nvia [PERT](https://en.wikipedia.org/wiki/Program_evaluation_and_review_technique)-like\n[activity-on-edges](https://en.wikipedia.org/wiki/Arrow_diagramming_method) diagrams\nwith focus on well-defined *events* (called *goals*) rather than activities.\nGoals are defined through their accomplishment criteria.\nDeclarative plans are often called *goal maps* (probably to pun on\nAlistair Cockburn's *project maps*) or [project networks](https://en.wikipedia.org/wiki/Project_network).\n\nDeclarative plans are\n* easy to construct and verify (compared to traditional activity-based plans)\n* scalable (can be written or collapsed to desired level of detail)\n* stable against (inevitable) business and technical risks (e.g. changes in requirements or architecture)\n\nFor more information on declarative planning see\n[Vlad's presentation on SoftwarePeople 2009](http://www.slideshare.net/gaperton/auftragsplanning-pre-final-1479467)\nor his numerous blogposts (sadly all in Russian):\n* [Как составлять планы, или \"декларативное планирование\"](http://gaperton.livejournal.com/16087.html)\n* [Инструмент планирования - notepad](http://gaperton.livejournal.com/56976.html)\n* [Инструмент планирования - notepad (2)](http://gaperton.livejournal.com/57204.html)\n* [Аннотация к моему докладу на SoftwarePeople](http://gaperton.livejournal.com/32051.html)\n* [Комментарий к \"декларативному планированию\"](http://gaperton.livejournal.com/32427.html)\n* [Guide for mastering project plans](https://gaperton.livejournal.com/25093.html)\n\n# Install\n\n`gaplan` is based on `setuptools` so to install simply run\n```\n$ pip3 install .\n```\nin `gaplan`'s folder.\n\nFor tooltips in TaskJuggler download [wz_tooltip.js](http://www.walterzorn.de/en/tooltip/tooltip_e.htm)\nto `scripts/` subfolder (note that it's distributed under LGPL).\n\n# How to use\n\nTo use the toolset you first need to write\na [declarative plan](http://gaperton.livejournal.com/56976.html).\nTake a look at example plans in `exampes/` folder (e.g. toolchain plan).\n\nNow to build a PERT chart, do\n```\n# Requires Graphviz dot.exe in PATH\n$ python3 -mgaplan pert plan.txt\n```\n\nTo generate TaskJuggler project:\n```\n# Requires TaskJuggler in PATH\n$ python3 -mgaplan tj plan.txt\n```\n\nTo compute project schedule (if defined for the project):\n```\n$ python3 -mgaplan schedule plan.txt\n```\n\nTo generate a burndown chart:\n```\n$ python3 -mgaplan burn --phase 'Iteration 1 completed' burndown plan.txt\n```\n\nTo display generated files (instead of passing it to Graphviz or TaskJuggler) use `--dump` flag e.g.\n```\n$ python3 -mgaplan --dump pert plan.txt \u003e plan.gv\n$ dot -Tpdf \u003c plan.gv \u003e plan.pdf\n```\nor\n```\n$ python3 -mgaplan --dump tj plan.txt \u003e plan.tjp\n$ mkdir -p tjdir\n$ tj3 plan.tjp -o tjdir\n```\n\nAll commands support `-W` (emit warnings for common errors)\nand `-v` (add diagnostic prints) switches.\n\nFor additional details run\n```\n$ python3 -mgaplan --help\n```\n\n# Notation\n\nThe core of the syntax is Vlad's text notation for graphs:\n```\n|Ready for NY celebration\n|\u003c-\n   |Bought food\n   |[X] Bread\n   |[] Cheese\n   |\u003c-\n      |Bought alcohol  // !3\n      |[] Wine\n      |[] Alcohol\n|\u003c-  // @me, 1h-2h\n   |Invited friends  // !3\n   |[] Alex\n   |[] Max\n```\n\nExample above illustrates few core concepts:\n* only goals have names (`Invited friends`), priorities (`!3`) and internal structure (checklists)\n* only activities (arrows) have duration (`1h-2h`) and assignees (`@me`)\nSee more examples in [examples/](examples) subfoler.\n\nCanonical notation has been extended with additional features which turned out to be useful in practice:\n* Tool tries to infer hierarchical connections between tasks (i.e. [WBS](https://en.wikipedia.org/wiki/Work_breakdown_structure)) as they allow to produce more readable plans for TaskJuggler.\n```\n# A hierarchy of 3 nested goals\n|Quality requirements fullfilled\n|\u003c-\n   |Results of regression testing acceptable for beta\n   |[] Regression testing logs ready\n   |[] Number of regressions against prev. version \u003c= 1%\n   |[] All regressions against prev. version fixed or explained\n   |\u003c-\n      |Results of regression testing acceptable for alpha\n      |[] Regression testing logs ready\n      |[] Number of regressions against prev. version \u003c= 5%\n```\n* Goals can be annotated with various attributes (priority, risk, assignees, etc.) e.g.\n```\n# This goal has to be reached by the end of November, has max risk and priority and has to be scheduled in first iteration\n|Symbol visibility in TZ 3.0 reduced  // deadline 2016-11-30, !3, ?3, I0\n```\n* In addition to normal dependencies (`|\u003c-`, `|-\u003e`) tools supports _global dependencies_ (marked with `global`). Globality causes all hierarchical children of a goal to depend on RHS. It's useful for splitting plan into disjoint phases, where task in depending phase can not start until their global dependency completes. This is an experimental feature.\n* Some goals many be unnamed (the so called \"dummy PERT goals\"):\n```\n|Feature X added\n|\u003c-  // 2d-1w\n   |\u003c-\n      |Prerequisite 1\n   |\u003c-\n      |Prerequisite 2\n```\n  Note that activity depends on unnamed implicit goal (which itself depends on Prerequisites 1 and 2).\n* Plan can specify a custom time-boxed schedule (see [SCHEDULE.md](SCHEDULE.md) for details).\n* Special syntax is used for describing project attributes e.g. duration or resources (see [PROJECT.md](PROJECT.md) for details).\n\n# Attributes\n\nGoals can be annotated with special *attributes* listed in table below.\n\n| Attribute                        | Syntax                | Example               | Comments     |\n|----------------------------------|:---------------------:|:---------------------:|:------------:|\n| Priority                         | !*PRIO*               | `!3`                  | 1, 2 or 3    |\n| Risk                             | ?*RISK*               | `?3`                  | 1, 2 or 3    |\n| Deadline                         | deadline *YYYY-MM-DD* | `deadline 2016-09-30` |              |\n| Accomplishment (or planned) date | *YYYY-MM-DD*          | `2016-08-31`          |              |\n| Identifier                       | id *symbolic\\_name*   | `id mod2_test`        | Short name   |\n| External issue                   | task *name*           | `task PRJ-123`        |              |\n\nPriorities use a 3-level scale:\n\n| Prio | Description                                               |\n|------|-----------------------------------------------------------|\n| 1    | Default                                                   |\n| 2    | Desirable but not required for project completion         |\n| 3    | Project requirement (probably stated in project proposal) |\n\nSame applies to risks:\n\n| Risk | Description                                                                    |\n|------|--------------------------------------------------------------------------------|\n| 1    | Know-how, have done similar stuff before                                       |\n| 2    | No prior experience but known to be doable (e.g. already done by someone else) |\n| 3    | No prior experience, not clear whether doable at all                           |\n\nPriorities propagate to predecessors (i.e. if some goal has high priority,\nit's predecessors will inherit it).\n\nFor example this statement\n```\n|Compiler rebuilds full distro  // deadline 2016-09-01, !3, ?1\n...\n```\nsays that the goal \"Compiler rebuilds full distro\" must be\ncompleted by September (`deadline` attribute), is high-prio (`!3`)\nand low-risk (`?1`).\n\nThere is a distinct set of attributes for activities:\n\n| Attribute          | Syntax                    | Example                    | Comment                                            |\n|--------------------|:-------------------------:|:--------------------------:|----------------------------------------------------|\n| Effort estimate    | *min*-*max*                 | `1h-3d`, `1w-1m`                   | Activity effort estimate (in [\"ideal hours\"](http://www.martinfowler.com/bliki/IdealTime.html)) |\n| Actual effort      | *min*-*max* (*real*)        | `1h-3d (1d)`, `1w-1m (2w)`         | Actual observed effort (used for tracking) |\n| Completion         | *min*-*max* (*X*%)          | `1h-3d (50%)`                      | Percentage of completion |\n| Actual duration    | *YYYY-MM-DD*-*YYYY-MM-DD*   | `2016-05-31-2016-06-02`            | Actual observed duration (used for tracking) |\n| Assignees          | @*dev1*/*dev2*/...          | `@yura/slava`                      | Developers assigned to the task |\n| Actual assignees   | @*dev1*/*dev2*/... (*real*) | `@yura/slava (max)`                | Developers who actually accomplished the task |\n| Parallel impl.     | \\|\\|                        | `\\|\\|`                             | Notes that developers can work on task in parallel |\n| Identifier         | id *symbolic\\_name*         | `id enable-jenkins-job`            | Gives symbolic name to activity |\n| Fast tracking      | over *id* *X*%              | `over enable-jenkins-job 15%`      | How much activity can be overlapped with it's predecessor(s) (multiple `over`s can be specified) |\n\nThe exact meaning of resource assignment attribute (@) depends on presense of \"parallel\" attribute (denoted with `||`):\n* with `||` (or `|| NUMBER`) - developers can work on task in parallel (e.g. it consists of many similar unrelated chunks)\n* without - only one of specified engineers will be selected to work on a task\n\nFor example, this activity\n```\n|\u003c-  // @yura/slava/max, 2h-1d\n```\ncan be done either by \"yura\", \"slava\" or by \"max\" (but not both simultaneously) and may require 2 hours to 2 days of effort.\nAdding `||` (or `|| 3`) would mean that all three developers will be able to work on parallel.\nAdding `|| 2` would mean that any two of them will be able to work in parallel.\n\nNote that you can not\n* assign names to activities (this forces you to focus on goals rather than tasks)\n* assign resources or efforts to goals (these are instantaneous events so they do not take any time to \"accomplish\")\n\n# Development\n\nInstall in editable mode via\n```\n$ pip3 install -e .\n```\n\nTo test, install `pytest-3` and run\n```\n$ pytest-3 gaplan\n```\n\n# TODO\n\n* Read arbitrary dates.\n* Fix remaining TODO and FIXME.\n* Add (many) more unittests.\n* Mark time- or risk-critical paths in PERT diagram.\n* Add include files.\n* Export to MS Project (Project Elements and XML Structure: https://msdn.microsoft.com/en-us/library/bb968652%28v=office.12%29.aspx).\n* Fast tracking in TJ.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyugr%2Fgaplan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyugr%2Fgaplan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyugr%2Fgaplan/lists"}