Roadmap

[skylarmacdonald]

Now that I've forked Bork, I should have a plan for its future. Looking at @mattly's 1.0 roadmap has informed a lot of where I want to go with Bork in the future. This is subject to change as things develop, but I would like to continue this work from that foundation where I can.

This roadmap has been edited in March 2022 with progress updates for each item.

Finish fleshing out each of the types

I just recently added outdated / update support and tests to npm, and there are more types where these are missing. I'd like to complete these.

I'd like to look through the types as they are now (this quote is from 2016, after all) and see where these can be added.

Update March 2022: This is well underway. More to do, but test coverage has definitely increased.

Add 'remove' commands to types, and an opposite of the ok assertion

This is something I've been thinking about for a while, and in theory it's not terribly hard. Mostly it's come down to semantics for what the opposite of ok is. So perhaps we alias ok to should or pass and then provide should-not or fail. So for example pass brew asserts the presence of homebrew, fail brew asserts the absence of it.

This would be a good one to sink my teeth into. It doesn't form part of my personal computing workflow, but for work previously it's been part of my IaC strategy to remove a bunch of packages from a fresh Linux install to clean it up a bit. So I see the merit of doing this. Just, now it's me that has to make that semantics decision. 😅

Update March 2022: This is done! The no assertion is the opposite of ok. This will have proper docs come v0.14.x, but it is usable now.

Improved CLI help

I see this as a two-pronged effort:

1. Man pages
2. a separate help system for individual types to get more details about their usage

No more to add here; I think both of these goals are reasonable. This also feeds into the next point, and some of the work I've started to do with bork docgen will inform the hosted documentation. Each type's desc function seems to be the logical place to start for per-type usage information.

Update March 2022: This is taking good shape. The website now lists documentation for all types using their desc functions, and there is a man page. Still more general docs work to be done — and the docs can always be improved, for sure — but again, lots of good progress here.

Static Website

I have borksh.com and a SSG tool I like working with already, I just need to figure out the Info Architecture and start putting things together. I see this site as serving two purposes: Marketing and Documentation. Marketing is the what and why, and Documentation is the how. I could use the most input on the marketing side of things. I have a rough plan for the docs that include both guides (to help learn) and reference (to help remind), and some good docs-focused friends to ping ideas off of.

I've begun this with the GitHub Pages site that I build from docs/, and the bork docgen which spits out each type's desc into a Jekyll-compatible Markdown file. It's really just fleshing out the text and making sure the documentation is properly thorough. borksh.com has since expired, but if this picks up enough steam I'll register it again.

Update March 2022: Thanks to sponsorship I have purchased https://bork.sh and published the docs/ folder there as a static Jekyll site. There isn't much in the way of marketing on there yet — it's basically just a copy of the readme and some extra technical info. I would like to work on improving this further.

---

I was always impressed by Bork's community, and anyone who had an interest in contributing to the original project is more than welcome here. If anyone else is still out there using Bork, I would love to read your hate mail thoughts in the comments.

[skylarmacdonald]

I have added a man page using ronn, and an Actions workflow that will compile it for us. I would like to tweak this so that it generates the man page in Markdown as well for the website (hence the sed hack in the workflow).

I think the best thing here would be to figure out some sort of overarching documentation strategy, as currently the same thing is now being said in three different places (man page, README, and website).

[hayduke19us]

I was looking for a place to just say thanks! I used bork for the first time years ago. While working thru a new work machine it was time to approach my unattended dotfiles. Your fork worked perfectly and it was awesome to be able to use such old setup scripts relying on this dependency. Thanks again!

[skylarmacdonald]

Thank you! That's very kind. It's what motivated me to fork it myself — I wanted to use it to set up a new computer I got last year, and something didn't work (I can't remember what), so I figured out how to fix it. The rest, as they say, is history :)