mindstream Mindstream anywhere

Summary of Changes

This proposes essential design changes to Mindstream to enable it to be used seamlessly in existing projects.

Addresses #7 #8 #9 #18 #23.

The rendered design document can be viewed here: Mindstream Design

To locally build the design doc and view it in a browser, you will need to have Racket installed. Then:

$ make design

Remaining Work

(copied and updated from the "changes from initial design" section in the design doc linked above)

[ ] Make "end session" prompt to squash+merge the branch into another one
[ ] Load project is no longer provided as a feature --- modify it to load sessions (change to branches) in the current repo.
[ ] Save session should prompt to rename the current branch, if it is a mindstream branch (Note: we still want to provide the ability to save anonymous projects, which is currently called mindstream-save-session. But we are starting to use the term session to refer to git branches. To resolve the collision, potentially rename mindstream-save-session to mindstream-save-project. Alternatively, use a new name like "stream" or "branch" for branches, and retain "session" as meaning repos/projects. The latter option is likely backwards compatible, but uses the term "session" to refer to what is more widely in the Emacs world referred to as a "project" (e.g. in project.el, projectile.el. We could potentially just mention this identification in the docs instead of introducing a backwards incompatible renaming).
[ ] Ability to view open sessions (without maintaining global state).
[ ] Ability to label and annotate versions (via tags).
[ ] Validate whether completion still works as expected, or whether there are any fresh settings where we need to handle it differently

WIP

Already Done

[x] Sessions are now branches in a repo rather than (effectively) entire repos – they can be begun anywhere, saved, loaded, merged.
[x] There is no longer any global state (i.e. eliminates mindstream-active-sessions)
[x] There can be more than one anonymous project active at any time per major mode (formerly just one). [already done on main branch]
[x] Anonymous projects are categorized by template (formerly flat). [already done on main branch]
[x] Saving an anonymous project moves (rather than copies) the project so that all open project buffers remain open. [already done on main branch]

Public Domain Dedication

[x] In contributing, I relinquish any copyright claims on my contribution and freely release it into the public domain in the simple hope that it will provide value.

(Why: The freely released, copyright-free work in this repository represents an investment in a better way of doing things called attribution-based economics. Attribution-based economics is based on the simple idea that we gain more by giving more, not by holding on to things that, truly, we could only create because we, in our turn, received from others. As it turns out, an economic system based on attribution -- where those who give more are more empowered -- is significantly more efficient than capitalism while also being stable and fair (unlike capitalism, on both counts), giving it transformative power to elevate the human condition and address the problems that face us today along with a host of others that have been intractable since the beginning. You can help make this a reality by releasing your work in the same way -- freely into the public domain in the simple hope of providing value. Learn more about attribution-based economics at drym.org, tell your friends, do your part.)

May 27 '24 22:05 countvajhula

I've drafted a document describing the proposed new UX @nobiot @greghendershott (rendered HTML linked in the description).

The purpose of the design refactor is to naturally support the notion of "sessions" on anonymous repos as well as existing projects, to further support the goal of being able to organically scale from absolutely nothing all the way up to a large scale project.

The essential change that's required for this is for "sessions" to be modeled by Git branches, so that beginning a session on an existing repo, at any commit, translates to just starting a branch there. This allows us to use Mindstream in existing projects without worrying about the noisy commits, since the mindstream branch could be squash-merged (and perhaps deleted) whenever it has served its purpose.

This is still a draft, and it would be valuable to have your feedback on it (and already incorporates some of our discussions). It uses an experimental notation intended to make it easy and unambiguous to discuss the UX. You're welcome to submit PRs against this PR to propose any modifications, but if you feel the notation is confusing we don't have to use it at all! I'm also happy to incorporate any suggestions into the document as we go.

We could consider this an "RFC" phase, where we incorporate any feedback or ideas into the document to arrive at a final design. Say after a few weeks (I know you mentioned you are busy at least till mid-June @nobiot), or whenever we feel it's ready, we could transition to working on the implementation, if you are interested and available of course (no pressure at all - just a fun opportunity).

Thanks so much folks. I feel Mindstream can be a widely useful tool, and with your help I'm sure it'll get there.

May 27 '24 23:05 countvajhula

Thank you. Will come back in June :)

May 28 '24 06:05 nobiot

Hello friends!

I was just taking stock today of what work the refactored design entails, and I'm realizing that it's not a lot. The recent work on #27 brought us closer by reducing reliance on global state, so I think there's just a few things to do on this before Mindstream can be used anywhere, with a good UX, even on existing repos!

I'd love to get to this in the near future and then write a nice blog post officially announcing the package, since there actually hasn't been an announcement of any kind so far.

This week, I'm focused on doing a new release of Qi with the nice folks in the Racket community (the release party on Friday is open to everyone -- feel free to stop by!)

But I'm thinking of jumping into this soon after that, in the trailing weeks of January. I'll aim to create issues to track the work that's needed, as well as add a task breakdown to the PR description. If you'd like to help out, as always, you're very welcome to. The more the merrier - but if not, no worries at all.

Really the one thing I will say is that Emacs completion is still very much black magic to me. Every time I've looked at it I've had a really hard time understanding how it works and how to make it do what I want. So I'm sure I could at least use help on this part.

I'll follow up soon!

Jan 14 '25 09:01 countvajhula

FYI I found some time and made a little progress. I've added TODOs to the PR description to track what remains 👍

Currently, things mostly work with starting mindstream- branches for new sessions, and relying on this branch name prefix to identify mindstream sessions, thus avoiding the need for a global dictionary tracking these.

But starting a new anonymous session (mindstream-new) errors with:

128 git … checkout -b mindstream-root HEAD
fatal: Cannot update paths and switch to branch 'mindstream-root' at the same time.
Did you intend to checkout 'HEAD' which can not be resolved as commit?

After seeing this error, manually calling mindstream-begin-session in the newly created anonymous project buffer does work, so my best guess is there's some timing-related issue, where copying the folder, running git init, and then git checkout -b ... in sequence, is running into some issue on disk where Git isn't yet done initializing, or something like that.

Just writing down my thoughts to pick up on later (or serendipitously get input on).

Mar 07 '25 05:03 countvajhula