Add development docs #2742

djmitche · 2022-03-05T23:49:59Z

This moves some development-related documentation into the repo, where it can be more easily co-versioned with the source.

It currently uses Jekyll via GitHub pages. You can see the result here. The theming could certainly be better, but I'm mostly focused on content right now. And, we could certainly move to use Hugo if y'all would prefer, but again: focused on content.

This just gets the docs in here. There's lots to be done, and I'll file issues for them if this gets merged:

contributing docs are repetitive and outdated and could probably be slimmed down to one or two files
we need some kind of RFC process. I had good luck with this one so I'd propose something similar. Nothing too heavy-weight, but some key milestones to know when a proposal can be acted on. The existing RFCs need also sorting into "abandoned" and "implemented". And I think "plans" is outdated enough to be removed.
documenting the task data model (based on this)

Fixes #2741.

tbabej · 2022-03-14T04:55:58Z

I think moving the content of the docs closer to the code is definitely the way to go - it will allows us to ensure correctness as the development progresses. I am not sure however, that we need to build and host the docs from this repo - perhaps we could simply check out the docs/ subfolder of taskwarrior in the tw.org repo as a submodule?

tbabej · 2022-03-14T06:23:12Z

tags

+v2.5.0.beta2
+v2.5.0.beta3
+v2.5.1.beta1
+


Unclear what this file is for, but I suppose we should trash it?

Oops, yes, that was a git add . mistake!

(now removed)

djmitche · 2022-03-14T14:55:07Z

The submodule idea is an interesting one, but then blocks this project on the markdown rewrite -- which is precisely the blockage I'm trying to avoid. It also depends on the deployment frequency of tw.org, which would have to be frequent or somehow triggered on a commit to this repository.

lauft

General comments:

Keep design/developer documents as simple Markdown files
Format "one sentence, one line" (leave linebreaks to the Markdown renderer)
Rename _index.md to README.md or <folder-name>.md or remove
Move images to common directory?

lauft · 2022-04-16T16:39:12Z

docs/contrib/build.md

+
+# Building the Stable Version
+
+The master always represents the more recently released version, and should be


master has become stable

lauft · 2022-04-16T16:40:09Z

docs/contrib/build.md

+
+# Building the Dev Branch
+
+The dev branch is always the highest numbered branch, in this example, `2.6.0`.


There are no more version branches, only develop for development

lauft · 2022-04-16T16:40:49Z

docs/contrib/build.md

+    $ ./problems         # Find errors in all.log
+
+
+# Submitting a Patch


Should be changed to pull-requests

lauft · 2022-04-16T16:41:11Z

docs/contrib/coding_style.md

+-   No cuddled braces
+-   Class names are capitalized, variable names are not
+
+We target Python 2.7 so that our test suite runs on the broadest set of


Guess that is Python 3 now...
Maybe state even at least Python 3.9 (according to https://python-release-cycle.glitch.me/)

lauft · 2022-04-16T16:45:36Z

docs/rfcs/_index.md

+title: "Taskwarrior - What's next?"
+---
+
+# Design


Add documents present in this directory, remove empty sections

Oops, I should have deleted this (fixed)

lauft · 2022-04-16T17:01:03Z

docs/contrib/branching.md

+title: Branching Model
+---
+
+Software development typically requires a standardized branching model, to


This document is somehow too general (mentioning 'hidden' topic branches on the developer's machine), also there is some overlap with other documents (build.md, development.md)

lauft · 2022-04-16T17:02:36Z

docs/contrib/first_time.md

+title: How to become an Open Source Contributor
+---
+
+Welcome, potential new Open Source contributor! This is a guide to show you


In general this document needs to be adapted to the new branching model (only stable/develop branches)

lauft · 2022-04-16T17:06:27Z

docs/rfcs/task.md

+
+Here are the standard attributes that may comprise a task:
+
+<table>


Reformat to Markdown table?

I did a few of these, where the Markdown table could reasonably replicate the HTML.

But on some of the never-finished RFCs with complicated tables it just wasn't worth the effort, so I left the tables as-is.

(in the end this was just the "plans" RFC, which is from 2016 and maybe should just be rm -rf'd?)

Deleting plans.md if it is outdated is fine with me. But as I am not directly involved in Taskwarrior development, I would delegate the final decision to @tbabej 😃

djmitche · 2022-04-21T00:22:25Z

Thanks for the review!

Keep design/developer documents as simple Markdown files

I'm not sure what you mean here. All of the docs files added in this PR are Markdown.

Format "one sentence, one line" (leave linebreaks to the Markdown renderer)

Sounds good -- I'll make that change and push it shortly.

Rename _index.md to README.md or .md or remove

This doesn't work with Jekyll. Would you prefer to not use GitHub pages?

Move images to common directory?

If you hadn't included ? I'd just do it on your say-so. But, these images "belong with" the docs that link to them, so it seems reasonable to put them in the same directory. I think a big reason to put images in "images" is that we used to have to configure Apache with different settings for those files..

To the more editorial comments above:

As I mentioned in the PR description, the plan here was to just get the docs moved -- it needs lots of work after that! I'd like to avoid doing so in this PR for a few reasons:

editing the documentation is necessarily a subjective exercise and I would expect disagreement with my opinions, leading to a lot of discussion;
getting these docs landed here is important to me in unblocking further documentation work that is orthogonal to editing what's here; and
ideally we can parallelize the followups, across multiple people or at least multiple PRs (so the uncontroversial stuff can land first).

I mentioned a few follow-ups in the PR description, and you've identified a few points included in the first ("contributing docs are repetitive and outdated") which I'd like to defer to that point.

lauft · 2022-04-22T06:42:00Z

Hi @djmitche

Keep design/developer documents as simple Markdown files
I'm not sure what you mean here. All of the docs files added in this PR are Markdown.
Rename _index.md to README.md or .md or remove
This doesn't work with Jekyll. Would you prefer to not use GitHub pages?

I would prefer to keep the developer documentation as simple and un-fancy as possible, i.e. just Markdown documents only, no web hosting. This would keep the Taskwarrior repository free of any 'side use' ( = hosting a web site). The Markdown documents can be linked, and IMHO browsing them on GitHub (like any other code file) is not that bad/cumbersome that it would require more CSS/etc. to increase user experience. However, this is my personal, "what I would do if Taskwarrior was my main project" opinion, so feel free to override it if you see benefits from any other decision... 😉

Move images to common directory?
If you hadn't included ? I'd just do it on your say-so. But, these images "belong with" the docs that link to them, so it seems reasonable to put them in the same directory. I think a big reason to put images in "images" is that we used to have to configure Apache with different settings for those files..

Fair point. There are not may images, so I am fine with this decision.

As I mentioned in the PR description, the plan here was to just get the docs moved -- it needs lots of work after that! I'd like to avoid doing so in this PR for a few reasons...
I mentioned a few follow-ups in the PR description, and you've identified a few points included in the first ("contributing docs are repetitive and outdated") which I'd like to defer to that point.

I definitely agree with that. Progressing in small steps is better than working on that big one forever.

lauft · 2022-04-22T06:07:44Z

docs/contrib/contribute.md

+
+-   Help [triage](/docs/triage) the issues list.
+
+-   Join the IRC channel \#taskwarrior on freenode.net and help answer some questions.


freenode is dead, long live libera.chat (👉🏻 https://web.libera.chat/#taskwarrior)

lauft · 2022-04-22T06:12:48Z

docs/contrib/contribute.md

+
+-   Join the IRC channel \#taskwarrior on freenode.net and help answer some questions.
+
+-   Join either the [developer-mailinglist](https://groups.google.com/forum/#!forum/taskwarrior-dev) or [user-mailinglist](https://groups.google.com/forum/#!forum/taskwarrior-user) (or both) and participate.


@tbabej I guess we should close down these and direct to our Discord (👉🏻 https://discord.gg/eRXEHk8w62) here...
Also, the main README mentiones Reddit, Twitter, and GitHub Discussions. Don't know, whether those are worth mentioning here.

I'm usually in the irc channel on libera.chat and I know there are several others I've seen / talked to there and which lurk or send a message, sometimes with days latency but responses occur mostly. I don't know much about the discord population, but we could keep mention of both irc and discord

lauft · 2022-04-22T06:17:33Z

docs/rfcs/task.md

+
+Here are the standard attributes that may comprise a task:
+
+<table>


Deleting plans.md if it is outdated is fine with me. But as I am not directly involved in Taskwarrior development, I would delegate the final decision to @tbabej 😃

djmitche · 2022-04-22T22:11:38Z

I'll leave the call on GitHub Pages to @tbabej then. I agree it's not critical, and linking to GitHub /blob/ renderings is adequate. If we choose to not use GitHub pages then I'll rename to README.md and verify that all of the links work.

tbabej · 2022-05-26T01:17:17Z

IMHO this is a great step forward to what we have right now, which is an absence of the development docs in this repo, hopefully enabling us to keep the docs more in sync with the changes. In the future I'd like to make the website repo use this as an authoritative source, but that's future work.

Thanks @lauft for all the suggestions 🙂

djmitche · 2022-05-26T02:49:03Z

@tbabej did you want to set up github pages for this? Or, should I make a PR to rename indexes to README.md? Or just leave it as-is?

tbabej · 2022-05-26T02:51:42Z

Yep, I'll setup github pages in the interim, right now I am trying to figure out the security audit permissions problem 🤔

djmitche · 2022-05-26T02:58:38Z

Awesome. https://stackoverflow.com/questions/70435286/resource-not-accessible-by-integration-on-github-post-repos-owner-repo-ac looks like it may be relevant there. Don't spend too long on it -- feel free to assign an issue to me instead if you'd prefer. I had hoped that merging some dependabot PRs would magically "fix" it but that's not realistic :)

djmitche requested review from tbabej and lauft March 5, 2022 23:50

tbabej reviewed Mar 14, 2022

View reviewed changes

djmitche added 3 commits March 15, 2022 01:06

Set up a basic Jekyll theme

728cac9

Bring contributing content from tw.org into dev docs

6a314f7

Import design docs (RFCs)

6bc7581

djmitche force-pushed the dev-docs branch from 8edfdc0 to 6bc7581 Compare March 15, 2022 01:07

lauft reviewed Apr 16, 2022

View reviewed changes

remove unused index

7adbb02

djmitche added 3 commits April 21, 2022 00:28

convert html table to markdown in rfcs/task.md

2bf6243

reformat to one sentence per line

5fd5f9a

eliminate unnecessary backslash-escaped quotes

beadade

djmitche force-pushed the dev-docs branch from 34ccfa0 to beadade Compare April 21, 2022 01:20

include images for contrib/branching

5a506f2

djmitche force-pushed the dev-docs branch from 6d887a7 to 5a506f2 Compare April 21, 2022 01:31

djmitche requested a review from lauft April 21, 2022 01:33

lauft approved these changes Apr 22, 2022

View reviewed changes

djmitche requested a review from tbabej April 22, 2022 22:10

tbabej merged commit 04f4d3a into GothenburgBitFactory:develop May 26, 2022

ryneeverett mentioned this pull request Jan 11, 2023

taskchampion: update docs #3046

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add development docs #2742

Add development docs #2742

djmitche commented Mar 5, 2022

tbabej commented Mar 14, 2022

tbabej Mar 14, 2022

djmitche Mar 14, 2022

djmitche Mar 15, 2022

djmitche commented Mar 14, 2022

lauft left a comment

lauft Apr 16, 2022

lauft Apr 16, 2022

lauft Apr 16, 2022

lauft Apr 16, 2022

lauft Apr 16, 2022

djmitche Apr 21, 2022

lauft Apr 16, 2022

lauft Apr 16, 2022

lauft Apr 16, 2022

djmitche Apr 21, 2022

djmitche Apr 21, 2022 •

edited

Loading

lauft Apr 22, 2022

djmitche commented Apr 21, 2022

lauft commented Apr 22, 2022

lauft Apr 22, 2022

lauft Apr 22, 2022

smemsh Apr 25, 2022

lauft Apr 22, 2022

djmitche commented Apr 22, 2022

tbabej commented May 26, 2022

djmitche commented May 26, 2022

tbabej commented May 26, 2022

djmitche commented May 26, 2022


		# Building the Stable Version

		The master always represents the more recently released version, and should be


		# Building the Dev Branch

		The dev branch is always the highest numbered branch, in this example, `2.6.0`.


		Here are the standard attributes that may comprise a task:

		<table>


		- Help [triage](/docs/triage) the issues list.

		- Join the IRC channel \#taskwarrior on freenode.net and help answer some questions.


		- Join the IRC channel \#taskwarrior on freenode.net and help answer some questions.

		- Join either the [developer-mailinglist](https://groups.google.com/forum/#!forum/taskwarrior-dev) or [user-mailinglist](https://groups.google.com/forum/#!forum/taskwarrior-user) (or both) and participate.

Add development docs #2742

Add development docs #2742

Conversation

djmitche commented Mar 5, 2022

tbabej commented Mar 14, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

djmitche commented Mar 14, 2022

lauft left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

djmitche Apr 21, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

djmitche commented Apr 21, 2022

lauft commented Apr 22, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

djmitche commented Apr 22, 2022

tbabej commented May 26, 2022

djmitche commented May 26, 2022

tbabej commented May 26, 2022

djmitche commented May 26, 2022

djmitche Apr 21, 2022 •

edited

Loading