I also enjoy Pieter Hintjens of ZeroMQ who wrote those issue documentation threads as commit messages. In fact, he forced the format to be different from the dominant practice of an imperative first line.
The point of the document, whether an issue or commit message, is to record why a change was made, and ancillary information considered along the way. So his commits, and issues, and pull requests, all started with the word “Problem:”. This told people they’d not be seeing what they expected, promoted the author to explain the context, and even allowed people to make imperative changes if they felt like it.
I have a hard time selling people on this format. ZeroMQ itself seems to have dropped it with Pieter’s death. But it seems a great example of temporal documentation, shipped with the code, that captures the mindset of the author at commit time.
One of my colleagues hates my Problem: first format. It reduces the usability of the commit messages as an ad-hoc changelog, and he’s right. On the other hand, I want the commit messages to be useful in the far future and the problem being solved gets more relevant as time goes on, and the details of a changelog get less relevant.
That’s the first time I hear about work notes being some form of “temporal documentation”. It makes a lot of sense.
I however think the workflow described in this page creates a hard dependency towards a online service by hard-linking internet URLs to your immutable and long-living git history. These URLS tend to be very mutable by nature, it’s hard to predict whatever they’ll still be available or not on a long time scale. Any migration would require you to re-write your whole git history.
That’s fine for your small hobby project, but it’s likely to lead to a lot of context loss in a moderately distant future (say 15/20 years) for a semi-major project (like datasette).
The git notes UX is pretty bad, it’s a shame. They’d be a great way to store this kind of temporal documentation attached to a commit.
[Edit]: Scratch that last paragraph, git notes wouldn’t work in a context where you want to store your design before starting to work on the actual implementation.
If you’re going to use issues in the way I’m describing here you need to be VERY confident that your organization has a healthy enough respect for institutional knowledge that they’re not just going to throw it all away some day when they switch to a different issue tracking system!
One of the reasons I’ve gone all-in on GitHub Issues is that it has a really good API. I have code which exports my issues on a regular basis, both as a form of backup and as a way to run my own queries against them: https://github-to-sqlite.dogsheep.net
My plan for if I ever do work on a project that migrates to another issue tracker is to create a static HTML archive of the old issues and then run a script that rewrites the entire commit history so each commit links to the full URL to the archived issue.
I don’t really understand the rationale of “avoid side projects with user accounts”.
It goes on to say that “Almost all of my projects right now are open source things that people can run on their own machines, because that’s about as far away from user accounts as I can get”.
I don’t really understand the difference here. First I was thinking about security, but it feels it’s even more true if people install it on their computers. So I am not sure where this comes from.
I still have a responsibility for shipping security updates and things like that, but at least I’m not holding onto other people’s data for them.
I mean it’s not like you have to hold a lot of data on them. A login for me is username (which doesn’t have to be email, which you might add for password reset) and password, the latter of which is usually salted in one way or another. So you have a username, a password that people usually don’t bother to attack and whatever your service has to store in terms of data.
But your software also holds that data if it’s on people’s computers. And it feels like there it’s a lot harder to manage where it goes.
If your side project has user accounts the following become true:
You need to provide active support. People will lose their passwords and need help recovering their accounts. People will have questions. You may need to deal with account deletion requests too (even GDPR stuff)
If there are any publicly visible parts of your service at all you’ll need to pay attention to moderation concerns - otherwise you’ll end up serving a hunch of spam links to things (best case scenario) or end up hosting fascist abuse or illegal material or worse.
You need to keep that system patched and secure, or your user’s data could be at risk
You need robust backups in place
You can’t just lose interest in the project and let the domain name / hosting payment card expire - if you’re going to shut it down you need to work with your users to make sure they don’t lose any data
Maybe I haven’t emphasized enough on the login and side project vs job part. I also think it depends on the definition of a side project though. None of this are complete disagreements, just some thoughts.
You need to provide active support. People will lose their passwords and need help recovering their accounts. People will have questions. You may need to deal with account deletion requests too (even GDPR stuff)
Active support seems to also be true for stuff they install software as well?
GDPR I think really depends on the project/data you collect. And account removal should really be a point in your settings, regardless of that. We talk about a side project, so I don’t think providing relevant information will be at the scale of a big company.
If there are any publicly visible parts of your service at all you’ll need to pay attention to moderation concerns - otherwise you’ll end up serving a hunch of spam links to things (best case scenario) or end up hosting fascist abuse or illegal material or worse.
While that makes sense, I always think small with a side project, not some social network. Also there’s plenty of people hosting web forums, etc. in their spare time. And for most of them it’s nowhere close to a job.
You need to keep that system patched and secure, or your user’s data could be at risk
Patching and security you really also should take care of if you run on other people’s computers because even more of their data might be at risk. So I don’t see a difference here.
You need robust backups in place
How robust they have to be depends on the scope of the side project though. For me here it’s about how it’s explicitly not a job. But yeah, you really want to have backups for anything anyways, like completely private stuff.
You can’t just lose interest in the project and let the domain name / hosting payment card expire - if you’re going to shut it down you need to work with your users to make sure they don’t lose any data
The domain part is a huge problem for software in general.
All makes sense. I feel like I’m probably way too used to this with side projects and hosting stuff for other projects in my spare time.
In other words a lot of this is tied to running a server and a community, and if you have some experience don’t shy away before thinking things through. It’s good to be daring, if it’s something you care about.
I want to encourage people to still dare to do things like this. So many amazing things only had a chance to go the route from spare side project to some form of company/club/association/society, because people dared these things. Just make sure to be upfront to any users. And things like GDPR really shouldn’t discourage you. If all you have about users is email, password and some basic data, just put it on the screen in their profile or something and allow for account deletion. Just make sure that you make clear it’s a one person project, if it is and you can therefor only make limited guarantees. And to ask for help, if you need help.
My advice to not take on projects with user accounts wasn’t meant to be taken completely literally - the actual advice I would give people is “and be really thoughtful if your project is going to involve user accounts - those require a whole host of extra responsibilities that you may not want to take on”.
In a talk I’ve found that making bold statements like this resonates with people more than adding a bunch of disclaimers - and my article is a written version of the talk.
I also enjoy Pieter Hintjens of ZeroMQ who wrote those issue documentation threads as commit messages. In fact, he forced the format to be different from the dominant practice of an imperative first line.
The point of the document, whether an issue or commit message, is to record why a change was made, and ancillary information considered along the way. So his commits, and issues, and pull requests, all started with the word “Problem:”. This told people they’d not be seeing what they expected, promoted the author to explain the context, and even allowed people to make imperative changes if they felt like it.
I have a hard time selling people on this format. ZeroMQ itself seems to have dropped it with Pieter’s death. But it seems a great example of temporal documentation, shipped with the code, that captures the mindset of the author at commit time.
Here are some examples for others as curious as me into how those commits look like.
I use a similar format, heavily inspired by Pieter’s writing.
I’d be curious to hear whether others are practicing with similar formats.
Vim follows that pattern. https://github.com/vim/vim/commit/4e6072b8d3e7ad85d2ca010c9172c2bdcdc62f44
One of my colleagues hates my Problem: first format. It reduces the usability of the commit messages as an ad-hoc changelog, and he’s right. On the other hand, I want the commit messages to be useful in the far future and the problem being solved gets more relevant as time goes on, and the details of a changelog get less relevant.
Great article!
That’s the first time I hear about work notes being some form of “temporal documentation”. It makes a lot of sense.
I however think the workflow described in this page creates a hard dependency towards a online service by hard-linking internet URLs to your immutable and long-living git history. These URLS tend to be very mutable by nature, it’s hard to predict whatever they’ll still be available or not on a long time scale. Any migration would require you to re-write your whole git history.
That’s fine for your small hobby project, but it’s likely to lead to a lot of context loss in a moderately distant future (say 15/20 years) for a semi-major project (like datasette).
The git notes UX is pretty bad, it’s a shame. They’d be a great way to store this kind of temporal documentation attached to a commit.
[Edit]: Scratch that last paragraph, git notes wouldn’t work in a context where you want to store your design before starting to work on the actual implementation.
I touched a bit more on that here: https://simonwillison.net/2022/Oct/29/the-perfect-commit/
If you’re going to use issues in the way I’m describing here you need to be VERY confident that your organization has a healthy enough respect for institutional knowledge that they’re not just going to throw it all away some day when they switch to a different issue tracking system!
One of the reasons I’ve gone all-in on GitHub Issues is that it has a really good API. I have code which exports my issues on a regular basis, both as a form of backup and as a way to run my own queries against them: https://github-to-sqlite.dogsheep.net
My plan for if I ever do work on a project that migrates to another issue tracker is to create a static HTML archive of the old issues and then run a script that rewrites the entire commit history so each commit links to the full URL to the archived issue.
I investigated exporting issue threads to git notes but was put off that idea when I learned the GitHub doesn’t display notes any more: https://github.blog/2010-08-25-git-notes-display/
I don’t really understand the rationale of “avoid side projects with user accounts”.
It goes on to say that “Almost all of my projects right now are open source things that people can run on their own machines, because that’s about as far away from user accounts as I can get”.
I don’t really understand the difference here. First I was thinking about security, but it feels it’s even more true if people install it on their computers. So I am not sure where this comes from.
I mean it’s not like you have to hold a lot of data on them. A login for me is username (which doesn’t have to be email, which you might add for password reset) and password, the latter of which is usually salted in one way or another. So you have a username, a password that people usually don’t bother to attack and whatever your service has to store in terms of data.
But your software also holds that data if it’s on people’s computers. And it feels like there it’s a lot harder to manage where it goes.
If your side project has user accounts the following become true:
It’s a big commitment!
Maybe I haven’t emphasized enough on the login and side project vs job part. I also think it depends on the definition of a side project though. None of this are complete disagreements, just some thoughts.
GDPR I think really depends on the project/data you collect. And account removal should really be a point in your settings, regardless of that. We talk about a side project, so I don’t think providing relevant information will be at the scale of a big company.
While that makes sense, I always think small with a side project, not some social network. Also there’s plenty of people hosting web forums, etc. in their spare time. And for most of them it’s nowhere close to a job.
Patching and security you really also should take care of if you run on other people’s computers because even more of their data might be at risk. So I don’t see a difference here.
How robust they have to be depends on the scope of the side project though. For me here it’s about how it’s explicitly not a job. But yeah, you really want to have backups for anything anyways, like completely private stuff.
The domain part is a huge problem for software in general.
All makes sense. I feel like I’m probably way too used to this with side projects and hosting stuff for other projects in my spare time.
In other words a lot of this is tied to running a server and a community, and if you have some experience don’t shy away before thinking things through. It’s good to be daring, if it’s something you care about.
I want to encourage people to still dare to do things like this. So many amazing things only had a chance to go the route from spare side project to some form of company/club/association/society, because people dared these things. Just make sure to be upfront to any users. And things like GDPR really shouldn’t discourage you. If all you have about users is email, password and some basic data, just put it on the screen in their profile or something and allow for account deletion. Just make sure that you make clear it’s a one person project, if it is and you can therefor only make limited guarantees. And to ask for help, if you need help.
I think we are in strong agreement here!
My advice to not take on projects with user accounts wasn’t meant to be taken completely literally - the actual advice I would give people is “and be really thoughtful if your project is going to involve user accounts - those require a whole host of extra responsibilities that you may not want to take on”.
In a talk I’ve found that making bold statements like this resonates with people more than adding a bunch of disclaimers - and my article is a written version of the talk.