4 ms·

> Sometimes I’ll even open an issue seconds before writing the commit message, just to give myself something I can link to from the commit itself! IMO generall

by thunky 4y ago

> Sometimes I’ll even open an issue seconds before writing the commit message, just to give myself something I can link to from the commit itself! IMO generally an issue should precede an implementation - it should track future work to completion, not work that is already complete. Creating a new issue and then immediately closing it is an anti-pattern, in the same way that creating a pull request and immediately merging it is.

simonw 4y ago
Most of my work has an issue created at the start of the development process and closed with the final commit. But occasionally I'll miss that step - maybe I dived straight in to fix a new bug without taking the time to open the issue first. This are the cases where I'll open an issue at the last possible moment - on the basis that an open-and-shut linked issue is still better than a bug fix with no associated issue at all.
- thunky 4y ago
  > an open-and-shut linked issue is still better than a bug fix with no associated issue at all It sounds like your issue tracker is a part time documentation repository. I think I view this as an anti-pattern because I look at the issue tracker as a shared collaboration tool for planning & tracking, not as a tool to document all code changes. For example, if I were solo I'd probably never create an issue (or a pull request).
  - simonw 4y ago
    > It sounds like your issue tracker is a part time documentation repository. Yeah, it's exactly that. I'm planning to write more about this. Basically I've started thinking of issues as "temporaral documentation" - documentation with an attached timestamp that was known to be accurate only at the point when it was written. A challenge with regular documentation is that when you first write it you are making a commitment to keep it up-to-date in the future. A project with thousands of pages of outdated documentation isn't much better than a project with no documentation at all (it might even be worse). But a project with thousands of pages of timestamped issue comments feels different to me: there's no expectation that those will be updated in the future, but they still offer enormous value in terms of capturing the decisions that lead to the present day. So yes: I do consider my issues as a form of documentation. They're not a replacement for traditional documentation, but they're a valuable extension to it.
    - thunky 4y ago
      That makes sense, although I think I would prefer to put pull requests in the "temporaral documentation" category rather than issues. But it sounds like your process is working well.

by thunky 4y ago

simonw 4y ago

Most of my work has an issue created at the start of the development process and closed with the final commit. But occasionally I'll miss that step - maybe I dived straight in to fix a new bug without taking the time to open the issue first. This are the cases where I'll open an issue at the last possible moment - on the basis that an open-and-shut linked issue is still better than a bug fix with no associated issue at all.

thunky 4y ago
> an open-and-shut linked issue is still better than a bug fix with no associated issue at all It sounds like your issue tracker is a part time documentation repository. I think I view this as an anti-pattern because I look at the issue tracker as a shared collaboration tool for planning & tracking, not as a tool to document all code changes. For example, if I were solo I'd probably never create an issue (or a pull request).
- simonw 4y ago
  > It sounds like your issue tracker is a part time documentation repository. Yeah, it's exactly that. I'm planning to write more about this. Basically I've started thinking of issues as "temporaral documentation" - documentation with an attached timestamp that was known to be accurate only at the point when it was written. A challenge with regular documentation is that when you first write it you are making a commitment to keep it up-to-date in the future. A project with thousands of pages of outdated documentation isn't much better than a project with no documentation at all (it might even be worse). But a project with thousands of pages of timestamped issue comments feels different to me: there's no expectation that those will be updated in the future, but they still offer enormous value in terms of capturing the decisions that lead to the present day. So yes: I do consider my issues as a form of documentation. They're not a replacement for traditional documentation, but they're a valuable extension to it.
  - thunky 4y ago
    That makes sense, although I think I would prefer to put pull requests in the "temporaral documentation" category rather than issues. But it sounds like your process is working well.