Mercurial > core / emacs/lib/scrum.el

 ;;; scrum.el --- Scrum-like Planning and Roadmaps in Org  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2024  Richard Westhaver
 
 ;; Author: Richard Westhaver <richard.westhaver@gmail.com>
 ;; Keywords: maint
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
 ;; the Free Software Foundation, either version 3 of the License, or
 ;; (at your option) any later version.
 
 ;; This program is distributed in the hope that it will be useful,
 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 ;; GNU General Public License for more details.
 
 ;; You should have received a copy of the GNU General Public License
 ;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Commentary:
 
 ;; The point of this package is to enable an Emacs-native scrum
 ;; workflow. Many years ago I used to use the org-jira package and
 ;; mirror an external scrum/agile system (Jira).
 
 ;; Mind you, I wouldn't dare take a shot at Jira. As far as Products
 ;; go, when you need to work with hundreds of humans on software and
 ;; are given a short list you must choose from, it's often the best of
 ;; the worst.
 
 ;; The problem is however, that we don't need Products. What we need,
 ;; is a plan. How we achieve that end should be via the best and most
 ;; powerful tools possible.
 
 ;; In my opinion, Emacs Org Mode is the most powerful tool
 ;; available. It is not quite the best tool for the job, but this
 ;; isn't a problem because it is not a Product. We are given the
 ;; opportunity to make it the best tool possible, in the only way
 ;; possible - by doing it ourselves.
 
 ;; And yes, the aura of NIH syndrome may be strong here. Most of the
 ;; time you need to work with lots of folks who don't have the need or
 ;; patience to learn Org-mode. This package isn't for them. It's for
 ;; small groups of like-minded Lispers :).
 
 ;;;; Refs
 ;; scrum: https://www.scrum.org/resources/what-scrum-module
 
 ;; roadmap: https://compiler.company/plan/roadmap.html
 
 ;; tasks: https://compiler.company/plan/tasks
 
 ;;;; API
 
 ;; The API is still very much a WIP. Assume everything below to be
 ;; theoretical.
 
 ;; - task dependencies
 ;;   - refer to org-depend.el for implementation details
 ;;   - org-trigger-hook and org-blocker-hook
 ;;   - org-todo-state-tags-triggers
 
 ;; - dynamic blocks
 ;;   - scrumboard
 ;;   - burndown
 
 ;;; Code:
 (require 'ulang)
 (require 'uml-mode)
 
 (defgroup scrum nil
   "CC Scrum Framework.")
 
 (defvar scrum-properties '("SPRINT" "EPIC" "RELEASE" "TASKID" "PROJECT" "COMMIT" "GOAL"))
 
 (defvar scrum-tags '("demo" "mvp" "release" "major-release" "ua" "qa"))
 
 (defun org-dblock-write:scrumboard ()
   "Generate a 'scrumboard'.")
 
 ;; TODO 2024-09-06: eplot
 (defun org-dblock-write:burndown ()
   "Generate a 'burndown' chart in the current buffer.")
 
 ;;; Projects
 ;; defining 'project' machinery here because we don't have a better
 ;; place to put it. These functions are intended to map projects
 ;; from 'skel' and 'project.el' into our task-based org system.
 
 ;; Projects can contain many subprojects, which are identified by org
 ;; headings with a 'PROJECT' todo keyword. Projects and sub-projects
 ;; all have a 'VERSION' property assigned which can't be
 ;; inherited. The 'PROJECT' property itself can be inherited.
 
 ;; project-info
 (defcustom org-project-info-order '(details status tasks churn log files)
   "Order in which sections of the 'project-info' dblock will appear."
   :type 'list
   :group 'scrum)
 
 (defun org-dblock-write:project-info (params)
   "Generate a project-info section.
 
 The following keyword parameters can be passed to the info dynamic block:
 
 :location Set or override the project location which is inferred by
           checking for a LOCATION property in the current tree, followed
           by the value of the `project-current' function.
 
 :branch Set or override the project branch to display info for. Default
         branch name is 'default'.
 
 :files When nil don't include the files table.
 :churn When nil don't include the vc churn report.
 :log when nil don't include the vc log.
 :status when nil don't include vc status.
 :details When nil don't include the project details section."
   (let ((location (or (when-let ((param (plist-get params :location)))
                         (cl-coerce param 'string))
                       (org-entry-get (point) "LOCATION")
                       (when-let ((kw (org-collect-keywords '("LOCATION"))))
                         (cadar kw))
                       (project-root (project-current))))
         (point (point))
         (files (if-let ((val (plist-member params :files)))
                    (cadr val)
                  t))
         (churn (if-let ((val (plist-member params :churn)))
                    (cadr val)
                  t))
         (status (if-let ((val (plist-member params :log)))
                     (cadr val)
                   t))
         (log (if-let ((val (plist-member params :status)))
                  (cadr val)
                t))
         (tasks (if-let ((val (plist-member params :tasks)))
                    (cadr val)
                  t))
         (details (if-let ((val (plist-member params :details)))
                      (cadr val)
                    t)))
     (message "Generating info for project: %s" location)
     (let* ((project (project-current nil location))
            (project-name (project-name project))
            (project-root (project-root project)))
       (dolist (i org-project-info-order)
         (pcase i
           ('details (when details
                       (message "building project details...")
                       (insert "#+CALL: project-details() :dir " project-root "\n")
                       (org-babel-execute-maybe)
                       (org-table-align)))
           ('status (when status
                      (message "building project status...")
                      (insert "#+CALL: hg-status() :dir " project-root "\n")))
           ('tasks (when tasks
                     (message "building project tasks...")
                     (insert "#+CALL: project-tasks() :dir " project-root "\n")))
           ('churn (when churn
                     (message "building project vc churn...")
                     (insert "#+CALL: hg-churn() :dir " project-root "\n")))
           ('log (when log
                   (message "building project vc log...")))
           ('files (when files
                     (message "building project file table...")
                     (insert "#+CALL: project-files() :dir " project-root "\n")))))
       (org-babel-execute-region point (point)))))
 
 (defun org-project-info ()
   "Insert or update a project-info dblock."
   (interactive)
   (if (re-search-forward (rx bol "#+BEGIN:" (+ space) "project-info") nil t)
       (progn
         (if (fboundp 'org-fold-show-entry)
             (org-fold-show-entry)
           (with-no-warnings (org-show-entry)))
         (beginning-of-line))        
     (org-create-dblock (list :name "project-info")))
   (org-update-dblock))
 
 (provide 'scrum)
 ;;; scrum.el ends here