# HG changeset patch # User Richard Westhaver # Date 1724559340 14400 # Node ID f747ffac7f40a06ce055ab8fb3444b396e9667e4 # Parent 6538a100c79279d304496ff541dca26bfe97555e meta and task work diff -r 6538a100c792 -r f747ffac7f40 babel.org --- a/babel.org Sun Aug 18 22:16:12 2024 -0400 +++ b/babel.org Sun Aug 25 00:15:40 2024 -0400 @@ -2,7 +2,7 @@ #+author: Richard Westhaver #+description: Core Library of Babel #+setupfile: ../clean.theme -#+property: header-args :exports both +#+property: header-args :exports both :eval no-export Welcome to the CC [[https://www.gnu.org/software/emacs/manual/html_node/org/Library-of-Babel.html][Library of Babel]]. This file contains a collection of code blocks which may be used by authors throughout our public documentation. @@ -67,7 +67,7 @@ :ID: d3c4ac69-337f-430b-a4db-760504f099ea :END: #+name: sum-str-nums -#+begin_src emacs-lisp :var s=tokei-dir-lines +#+begin_src emacs-lisp :var s=tokei-dir-lines() (let ((tot 0)) (cl-loop with tot = 0 diff -r 6538a100c792 -r f747ffac7f40 business.org --- a/business.org Sun Aug 18 22:16:12 2024 -0400 +++ b/business.org Sun Aug 25 00:15:40 2024 -0400 @@ -3,7 +3,6 @@ #+email: ellis@rwest.io #+description: The Compiler Company Business Model #+setupfile: ../clean.theme -#+glossary_sources: glossary.org In short, this document describes the business aspects of The Compiler Company LLC. We are designed to be small, fast, and agile. We infiltrate a market, apply our methodology, and develop solutions that diff -r 6538a100c792 -r f747ffac7f40 style.org --- a/style.org Sun Aug 18 22:16:12 2024 -0400 +++ b/style.org Sun Aug 25 00:15:40 2024 -0400 @@ -2,7 +2,6 @@ #+author: Richard Westhaver #+email: ellis@rwest.io #+setupfile: ../clean.theme -#+glossary_sources: glossary.org As an organization we maintain a styleguide[fn:1] which lists all of the style guidelines we use for our code. If you are contributing to one of our projects, you should review and understand the relevant diff -r 6538a100c792 -r f747ffac7f40 tech.org --- a/tech.org Sun Aug 18 22:16:12 2024 -0400 +++ b/tech.org Sun Aug 25 00:15:40 2024 -0400 @@ -3,15 +3,6 @@ #+email: ellis@rwest.io #+description: The Compiler Company Core Technologies #+setupfile: ../clean.theme -#+glossary_sources: glossary.org -* OS -:PROPERTIES: -:ID: 0c3a8097-e0bb-4c8a-9de2-907cffddbb8f -:END: -We primarily support [[https://unix.org][Unix-based]] Operating Systems. Check -project-specific docs for officially supported targets. - -Development and CI is ran on [[https://archlinux.org/][Arch Linux]] (btw). * Core :PROPERTIES: :ID: f6d8cc58-e6ec-4482-b6b8-3977e771a578 @@ -69,7 +60,7 @@ :ID: 3cc89f3d-20a5-420f-bc7e-0731254e5040 :END: -* Our Software +* Software :PROPERTIES: :ID: 06de34a3-60b4-4f48-bcab-eabeb3fe41c3 :END: diff -r 6538a100c792 -r f747ffac7f40 ulang.org --- a/ulang.org Sun Aug 18 22:16:12 2024 -0400 +++ b/ulang.org Sun Aug 25 00:15:40 2024 -0400 @@ -3,8 +3,6 @@ #+email: ellis@rwest.io #+setupfile: ../clean.theme #+infojs_opt: toc:nil home:https://compiler.company up:./ view:showall -#+print_glossary: :level 0 :consume yes :all yes :only-contents no -#+glossary_sources: glossary.org * Introduction :PROPERTIES: :ID: e63d129f-9024-4cd8-9e2c-77f4bc614663 @@ -36,7 +34,7 @@ - This document is for authors and curious readers. It is a loose specification, but also serves as introductory material into our - communication and design philosophy. + communication style and design philosophy. - All sources we write attempt to comply to this standard but it is not strictly enforced. If there is a reason to not comply with a rule, it is already broken. @@ -54,39 +52,13 @@ If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't be getting too deep into tribal hacker knowledge of Emacs. -What's important to know is this: There is /Org Syntax/ and -/Org-mode/ - these are different things. - -Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are -not concerned about /Org-mode/ the application in this document. - -For the remainder of this document, we assume basic knowledge of Org -Mode. - * ulang :PROPERTIES: :CUSTOM_ID: ulang :ID: 236227a5-b30c-4548-8cad-360428d74d67 :END: Our *U-Language* is colloquially termed *ulang*. Each section of this -document describes a feature or property of our ulang. -** Glossary -:PROPERTIES: -:ID: cf237775-6e69-4554-999d-7c9cc4445f77 -:END: -*** Terms -:PROPERTIES: -:ID: e808e546-65fb-4470-a21f-27eb9a7b50ee -:END: -*** Acronyms -:PROPERTIES: -:ID: c04c4524-a3d6-495d-98be-8ca291c5db08 -:END: -** Dictionary -:PROPERTIES: -:ID: 689826b6-0df4-4f0e-944a-b96fa4f8599e -:END: -compiler.company:2628 +document describes a feature of our ulang. ** Emphasis :PROPERTIES: :ID: 88bf1177-b5b7-4945-8bdc-5229803e617e @@ -110,6 +82,15 @@ Text emphasis markers may be embedded in any syntax as long as it does not cause any conflicts with the host language. +** Links +:PROPERTIES: +:ID: 7ecaec5d-c656-44e1-8fad-185915655cee +:END: +*** Link Types +:PROPERTIES: +:ID: 6aedc026-36d0-4763-adc8-8ae1a79f1b3e +:END: + ** Headings :PROPERTIES: :ID: ed035298-f7fa-4726-ad58-2d542323bb61 @@ -151,85 +132,33 @@ println!("H1"); #+end_src -** Outlines -:PROPERTIES: -:ID: 7b4d3229-d85f-4464-b9d0-6beccb1f7b2e -:END: -A collection of /headings/ is what we call an *Outline* - which is -also the name of the major-mode utilized for this feature and of -course - what Org itself is derived from. ** Keywords :PROPERTIES: :ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba :END: -In Org, TODO keywords are used to key track of the state of a [[https://orgmode.org/manual/TODO-Items.html][TODO -Item]]. +TODO keywords are often used to keep track of the state of a [[https://orgmode.org/manual/TODO-Items.html][TODO +Item]], but may also be [[https://orgmode.org/manual/TODO-Extensions.html][extended]] to support a variety of stateful item +types beyond just simple tasks. -In ulang, they are used for this purpose and [[https://orgmode.org/manual/TODO-Extensions.html][extended]] to support a -variety of stateful item types beyond just tasks - for example =NOTE= -and =PROJECT=. - -The following keywords indicate the state of a heading element. They -often appear as the first word in a heading. +The following keywords form the simple set of task states. -- TBD :: A task to be done at a later date. -- TODO :: A task yet to be done. -- FIXME :: Item that needs fixing. -- WIP :: Work In Progress task. -- WAIT :: A suspended task. -- DEAD :: Item that will not be completed. -- DONE :: Completed task. -- BUG :: Designate a bug item. -- IDEA :: Designate an idea item. -- NOTE :: Designates a note item. -- DRAFT :: Designates a draft item. -- COMMENT :: A 'commented' item. -- PROJECT :: Designates a project item containing a sequence of tasks. +- TBD +- TODO +- WIP +- HOLD +- WAIT +- DONE +- NOPE #+begin_src org ,* PROJECT project ,** DONE foo ,** TODO bar + ,** TBD baz + ,** WIP test foo #+end_src -** COMMENT Tasks -:PROPERTIES: -:ID: 0f4c0afd-a774-4b98-900b-1ab44f9fd2ef -:END: -Tasks as they are known in Org, usually consist of a heading that -starts with a [[id:2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and -metadata which are present in our collection of tasks. - -Our task management system is roughly a hybrid of two more -conventional methods: GTD and Agile. For convenience I will describe -these styles and how I use them separately, but the concepts may be -spliced differently in real tasks. - -- *GTD* \\ -- *Agile* \\ - It's a dirty word in some tech circles - the dreaded PIs, daily - standups, and still nobody knows what's going on, Oh my! Do not - worry. For the most part we just borrow the vocabulary. - - Our /Agile/ workflow consists of roadmaps, features (epics/ARTs), - issues (user stories), and of course, tasks. -** Properties -:PROPERTIES: -:ID: 174a993b-a5dc-4324-b4f8-dda8101a55b7 -:END: -*** IDs -:PROPERTIES: -:ID: 3944c851-e46c-4d75-b8f5-07b5c052177a -:END: -We reference two different types of identifiers in documentation: -- UUID :: =ID= property -- User-defined :: =CUSTOM_ID= property - -Most of the time these IDs don't add any information for the reader - -the UUIDs are used to index and graph documents, CUSTOM_IDs are for -convenience but are rarely necessary given the many ways of -identifying a headline. ** Tags :PROPERTIES: :ID: a7ae1b2a-559e-46e9-8cab-33e39a218288 @@ -240,12 +169,16 @@ A tag can be any text without newlines, although it is recommended to treat them as unique identifiers and usage of whitespace is discouraged (but not disallowed). -*** Tag Types + +#+begin_src org + ,* foobar :tag1:tag2:@home:!today +#+end_src +*** Tag Prefixes :PROPERTIES: :ID: b686dbc5-3505-49d7-b66a-0772bcf1a726 :END: -Tags may be prefixed with one of the following characters, indicating -a special tag type: +Some of ourtags are prefixed with a character which indicates a +special tag category: - =@= :: location-tag \\ A /location tag/ refers to some context-dependent named point in space, such as a user's home address, a popular fast food @@ -260,15 +193,32 @@ - =#= :: anchor-tag \\ An /anchor tag/ implies a link to the object identified by some [[id:3944c851-e46c-4d75-b8f5-07b5c052177a][ID]]. - =#readme=, =#a7ae1b2a-559e-46e9-8cab-33e39a218288=, =#custom-id= -*** Tag Lists -:PROPERTIES: -:ID: 805862be-ba2b-4288-a2e3-791c0aa3802f -:END: -** Links +** Properties :PROPERTIES: -:ID: 7ecaec5d-c656-44e1-8fad-185915655cee +:ID: 174a993b-a5dc-4324-b4f8-dda8101a55b7 :END: -*** Link Types +[[https://orgmode.org/manual/Properties-and-Columns.html][Properties]] are key:value pairs which are associated with a heading or +file and stored in a dedicated [[https://orgmode.org/manual/Drawers.html][Drawer]]. + +#+begin_src org + ,* WIP do stuff :@lab: + :PROPERTIES: + :CREATED: <2024-08-24 Sat 19:09> + :ID: 62da3982-7a83-4b27-ab7e-55949fd3e2a3 + :EFFORT: 24:00 + :END: +#+end_src +*** ID :PROPERTIES: -:ID: 6aedc026-36d0-4763-adc8-8ae1a79f1b3e +:ID: 3944c851-e46c-4d75-b8f5-07b5c052177a :END: +We reference two different types of identifiers in documentation: +- UUID :: =ID= property +- User-defined :: =CUSTOM_ID= property + +Most of the time these IDs don't add any information for the reader - +the UUIDs are used to index and graph documents, CUSTOM_IDs are for +convenience and extensions, but are rarely necessary given the many +ways of identifying a headline. + +All headings are assigned an ID automatically and are never changed. diff -r 6538a100c792 -r f747ffac7f40 workflows.org --- a/workflows.org Sun Aug 18 22:16:12 2024 -0400 +++ b/workflows.org Sun Aug 25 00:15:40 2024 -0400 @@ -1,61 +1,197 @@ -#+title: meta/workflows +#+title: Workflows #+author: Richard Westhaver #+email: ellis@rwest.io -#+description: Meta Workflows +#+description: High-level description of CC workflows #+setupfile: ../clean.theme -#+glossary_sources: glossary.org -* Roadmap +* Overview +:PROPERTIES: +:ID: ad4a24f8-7de4-479b-bc5a-7065e4b43087 +:END: +* Workflows :PROPERTIES: -:ID: be90c808-6c3b-4381-a032-af07d54f5907 +:ID: 51b210fd-0ba1-41c1-a4ec-85c3d9295c02 +:END: +** Items +:PROPERTIES: +:ID: 249ae0a5-0ef8-4d8a-be61-f408fb2b2cff +:END: +*** Simple Items +:PROPERTIES: +:ID: b7f9c275-90fd-407f-aa39-615fa6ab64d6 :END: -The [[https://compiler.company/plan/roadmap.html][roadmap]] is a high-level document which describes the strategic -plan associated with some pre-determined period of time, such as a -year, month, or quarter. +When an item has no task-related state associated with it, it is +considered a /non-task/ or /simple item/. -* Archive +Simple items imply that there's no action directly associated with +this item, but it may contain child items which are tasks with action. +**** Note +:PROPERTIES: +:ID: a7c60105-171a-4960-b2fc-3a8611ce210b +:END: + +**** Link :PROPERTIES: -:ID: ca0dcc07-0517-4d04-86f0-905537cb7801 +:ID: daf2c376-1969-48f9-bdbd-1a5f066e8109 +:END: +**** Code +:PROPERTIES: +:ID: 81da5e76-2619-42c3-8a2a-dea2b815b261 :END: -When an item is archived, it is moved to a file under version-control -in the [[vc:comp/archive][archive]] project. -* Task Management +There is a dedicated =CODE= keyword available for headings +dedicated to a specific piece of code. + +All CC code is kept under version control and intended to be linked +directly using the =vc= link type. Code can be linked anywhere - +including org documents, other code, or online. In org documents, =vc= +links are often used as the value of the =LOCATION= property. +*** Simple Tasks :PROPERTIES: :ID: 66333c80-aa6f-43d7-a305-44e218dde045 :END: Tasks are most often found as headings with some additional metadata such as scheduling info, priority, clock info, and special properties. -Task keywords are always part of a sequence with at least one =TODO= -state and one =DONE= state. -* Project Management +Tasks are always *stateful* and exist somewhere in one of the +following abstract /todo states/: + +- TODO :: Incomplete task +- WIP :: Work In Progress task +- DONE :: Completed task + +Tasks are easily identified by a [[id:2cadda9a-22a3-4b42-ad4e-d7a774f74cba][keyword]] which represents the current +state. Tasks always follow a sequence with at least one 'TODO' state +and one 'DONE' state. There is always an implied 'WIP' state in the +sequence which come after the TODO keywords and before the DONE +keywords. + +*** Project Items :PROPERTIES: :ID: 560f4094-e077-4389-9e09-dba1e0d4004e :END: Projects are denoted by the special keyword =PROJECT= and act as -formal units of organization. +containers of related work to be done. They may contain the same +metadata as tasks, and may be 'downgraded' to or 'upgrade' from tasks. -* Code Management +Projects often contain additional metadata, such as =CATEGORY= and +=VERSION= properties. +** Inbox :PROPERTIES: -:ID: 81da5e76-2619-42c3-8a2a-dea2b815b261 +:ID: 1b426ef7-b88b-4b66-8413-df37d8312dcd +:LOCATION: [[vc:comp/core/-/blob/branch/default/emacs/lib/inbox.el][inbox.el]] :END: +The inbox is a flat list of [[id:249ae0a5-0ef8-4d8a-be61-f408fb2b2cff][items]] usually found in the +=org-inbox-file= (default is ~/org/inbox.org). Items are [[https://orgmode.org/manual/Capture.html][captured]] by +various means and then [[https://orgmode.org/manual/Refile-and-Copy.html][refiled]] to another location. -* Data Management +As of [2024-08-24 Sat] we capture items manually and in a local-only +fashion. In the future this may change to support automatic capturing +via org-protocol and email as well as peer-aware/group inboxing. +** Scrum :PROPERTIES: -:ID: e5c4702e-581d-41b7-a484-76730435f056 +:ID: 44e6ff33-ad62-4ef0-a188-506f837648d8 +:LOCATION: [[vc:comp/core/-/blob/branch/default/emacs/lib/scrum.el][scrum.el]] :END: -** Tables +We apply a [[https://www.scrum.org/resources/what-scrum-module][scrum]]-like framework to plan our projects and tasks. + +We borrow the same terminology where possible but do not align with +any specific implementation. Here are some noteworthy implementation +details: +- We utilize the =EFFORT= property with time values as the basis of + estimation such as =1d=, =24:00= or =24h= as opposed to [[https://www.scrum.org/forum/scrum-forum/33290/age-old-question-story-points-vs-hours][story + points]]. We measure progress in time too, but we don't /represent it/ + as such. We effectively represent it as some form of 'story point' + like a percentage. This is because the estimates don't reflect + realtime and shouldn't be intertwined with measures of performance. +- Realtime values can be found in the scheduling and clock metadata as + well as some timestamps like the =CREATED= property. + - Performance-related metrics may be derived from the clock + metadata, but I have always found it tedious to [[https://orgmode.org/manual/Clocking-Work-Time.html][clock work time]] in + Org mode. As of [2024-08-24 Sat] this is still unresolved, but we + have some ideas to improve the workflow and implement some + automatic clocking. +- Products and Projects are separate entities. As a rule, any task + belonging to a product is unable to block a project. +*** Roadmap :PROPERTIES: -:ID: 8433beaf-59de-4b13-a066-8d3e636066a1 +:ID: be90c808-6c3b-4381-a032-af07d54f5907 +:END: +The [[https://compiler.company/plan/roadmap.html][roadmap]] is a high-level document which describes the strategic +plan associated with pre-determined period of time called program +increments or PIs. The current length of a PI is 1 year. +*** Projects +:PROPERTIES: +:ID: b94e643b-479c-400b-9679-0eb843a782fa :END: -* Knowledge Management +For every major project in our portfolio there is a dedicated list of +tasks. This list can contain any type of heading at any level but will +usually consist of top-level project items containing sets of +tasks to be completed. +*** Products :PROPERTIES: -:ID: ad28e021-657d-4073-b541-336df389c9fb +:ID: 5576df8c-7cc3-4d7b-a5df-9201c278a08a :END: +Products are an implementation of the value our projects provide. They +represent a tangible end-goal, an anchor point for connecting with +potential users and supporters, and collecting feedback. ** Notes :PROPERTIES: :ID: 6ebed997-12c0-4a20-88ef-df8cf424b198 :END: +Notes should be collected frequently and referenced often. They can be +as simple as a link to a Wikipedia page, or contain a complex tree of +inter-connected nodes. + +*** User Notes +:PROPERTIES: +:ID: 33ac913a-1697-49d6-8d80-542b5a1f83ec +:END: +How you store your own notes is a very personal decision, and so I +think it's important to leave a space for users to store their own +notes and make their own decisions on how to use them. + +As of [2024-08-24 Sat] there is no API for this at all - in the future +we will likely provide an API and default implementation specifically +for user notes. +*** Graphs +:PROPERTIES: +:ID: 92d71908-dba3-41b7-a126-0c6415b54579 +:END: +Graphs are a set of inter-connected nodes inspired by Roam and +Zettelkasten (see [[https://github.com/org-roam/org-roam][org-roam]]). + +As of [2024-08-24 Sat] this has not been implemented, but we intend to +implement a fully connected knowledge graph. See [[vc:comp/core/-/blob/branch/default/emacs/lib/graph.el][graph.el]]. ** Documentation :PROPERTIES: :ID: 03e13d7e-6cda-46d4-830f-5671518bd32f :END: +*** README +:PROPERTIES: +:ID: 111db7b0-61e0-4be3-8ec7-1a68913997ff +:END: +For every project under version control there is a =readme.org= file +in the root directory. This file contains some dynamic blocks of basic +information followed by additional content introducing the project. +*** REF +:PROPERTIES: +:ID: 26532798-89ca-4d15-aabe-e57122dea07d +:END: +API References are generated for some of our projects based on the +source code. In general these documents are generated automatically +and highly structured. +*** MAN +:PROPERTIES: +:ID: 4a299f6e-b176-43bd-88fc-3cbdde1cc2d6 +:END: +User Manuals serve as the subject of the phrase 'RTFM'. These are +always written manually and revised regularly to stay accurate. +** Report +:PROPERTIES: +:ID: 307ba3e8-ef19-48da-a3c9-f5a46d6819e9 +:END: +** Archive +:PROPERTIES: +:ID: ca0dcc07-0517-4d04-86f0-905537cb7801 +:END: +When an item is archived, it is moved to a file under version-control +in the [[vc:comp/archive][archive]] project.