search

littlemanco / www.littleman.co

Website
1 stars 1 forks source link

As a developer I'd like to know more about consuming git (and logs) #27

Closed andrew-howden closed 5 years ago

andrew-howden commented 5 years ago

There are a series of articles about "how to write git logs". However, they don't really go into reason as to why git logs need to be written in that way.

There are various ways to consume the parts of git;

As well as

All of which are super useful -- if the participant has followed git conventions

I'd expect this documentation to be in the form of an article.

welcome[bot] commented 5 years ago

Hey welcome! We're super happy that you're getting started here.

As much as possible it's good to follow the templates that are supplied when creating an issue. They're designed to make sure that we have all the information that we need to further develop the project.

Feel free to ask for further clarification here, or check out the docs for further details.

andrew-howden commented 5 years ago
  1. We have a bug
  2. We need to understand how bug got introduced
  3. Bugs are usually introduced as things changed, and due to differing models of how the software should work. So, examining changes can be illustrative to point to bugs
  4. Annotate → show patch

This justifies good shortlog, description, justification etc.

It also means git is a mechanism to understand a codebase; given this, we need to be clear on why, we're making a particular change, as well as what constrains we're under when making it.

Software is not simply code; it's code made in an environment, and under constraints. When designing it, we need to understand all of the above.

andrew-howden commented 5 years ago

We are looking to understand all references to ${X} function. So we run git log -S${FUNCTION} --patch. That tells us who edited it and why, and shows the story over time.

andrew-howden commented 5 years ago

(If you're similar to me and learning how stuff works in project) a useful git feature is the "pickaxe":

git log -S 'XX' --patch

It finds any occurrence of XX in the previous patchsets and shows the log. You can use --patch to show the changes made and see how a previous person did a thing (And presumably how we should do it in future)

andrewhowdencom commented 5 years ago

Should do this something like:

  1. "I need to ${X}" (make these concrete stories)
  2. "Here's how to ${X}"
  3. "Here's how to maximize the utility of ${X} while writing a commit"
andrew-howden commented 5 years ago

git add --patch

stale[bot] commented 5 years ago

This issue has not received any updates in quite some time. It's not clear whether it's still relevant, and should be kept. If there is no more activity in the next 14 days on this ticket, I will close it. It can always be reopened later, but for now in the interests of keeping the project as clear and simple as possible it will be closed. If you'd like to keep it open simply comment:

"This needs to remain open"

And I will leave it alone for the next 90 days or so. Alternatively, if you are already sure that this is no longer relevant you can also close it directly. For more information see:

https://l.littleman.co/2XnF2B3