15 ms·
The Perfect Commit
- WesolyKubeczek 4y agoMy perfect commits have message „WIP on stuff”, include changes to code coupled with formatting changes, have zero tests, nada documentation, and no links to issues. But they are perfect nevertheless, because I judge them so. And because the code works. Also, because I get to get out more.
- simonw 4y agoThis post was extracted from a talk I gave at DjangoCon a few weeks ago, which was about how this kind of workflow has /increased/ my personal productivity by a material amount. https://github.com/simonw/djangocon-2022-productivity https://github.com/simonw/djangocon-2022-productivity So I get to get out more because I'm doing this!
- WesolyKubeczek 4y agoYou may think so ;)
- airstrike 4y agoI feel seen
- js2 4y agoI wanted to get out today, but instead I spent two hours debugging an issue because I was dealing with code from someone who thought like you who didn't think documentation, comments, meaningful commit messages, or tests were a good use of their time. I don't care what you do with your code, but as soon as someone else inherits it, you're a sociopath if you didn't document anything along the way. And btw, the person who inherits that code may be your future self, and you'll thank your past self for writing down why you did something the way you did.
- WesolyKubeczek 4y agoDo you think I should also document all the bugs I put in my code? If I knew they were bugs, I wouldn’t be putting them there in the first place. I may be crazy, but a moron I’m not.
- js2 4y agoYou should document what the code should do, why it exists, and why you did it a certain way. In my current role, I've inherited a decade of cobbled together shell, python, ruby, javascript, java, and groovy that together constitute a large part of our build release system, spread across a dozen or more repos, written by over a dozen developers. This code is undocumented, untested, brittle, and riddled with heisenbugs. Among other things was a developer who was terrified of ever breaking anything. So whenever he needed to make a change, he'd duplicate the code. One recent example I dealt with is three copies of a script: copyReports.sh, copyReports-alt.sh and copyReports-multi.sh. In addition are symlinks to each script without the .sh extension. Before I could even touch this code I first had to instrument it to record when it was run, to figure out which of these was even in use, and under what circumstances. I had to try to tease out why the developer made the extra copies, because he didn't document the reason when he did so. I had to guess why there were both version with the '.sh' extension and why not. The developer hadn't written so much as a single sentence explaining his thinking at the time. So no, I don't expect you to document your bugs, but maybe in the process of writing a commit message, or a test, or some documentation, you may realize on the second thought that you made an error in the code and save yourself from a bug. But in any case, at least when you come across your bug a year from now, it'll be clearer what the code was supposed to do because you wrote it down at the time, as opposed to what it actually did. WesolyKubeczek, can I ask how long you've been a developer and what size projects you've worked on? I've been writing code professionally for over 20 years, worked at companies and on projects big and small, and have used revision control systems since RCS/SCCS, on through clearcase and subversion, mercurial and git. I've worked with code old and new. In my experience, documenting things along the way is invaluable to building a sustainable code base. You may think that shipping and velocity is all that matters and that writing a commit message is nothing but friction. But that hasn't been my experience, neither at startups nor at fortune 500s. Code that's going to be around more than 6 months is going to be revisited. To add features. To fix bugs. Even just to delete it. And when that time comes, having a commit message saves time, much more time than was spent writing the message in the first place. I personally consider it development malpractice not to document my code along the way.
- DangitBobby 4y agoI honestly feel that any sort of documentation in commits themselves (besides a short, concise summary of what and maybe why) is a waste. It's one of the least likely places people will be looking for that information. A better place is in comments near the code, though obviously that has its own issues.
- ziml77 4y agoI agree. It's much better to just have all of the key info inline. If I look at the commit history of a file, there's going to be such a mess of irrelevant commit messages to the issue I'm looking at that it's hardly worth spending the time trying to find if the info is there.
- pkrumins 4y agoMy definition of a perfect commit is any commit that goes to production because only shipping matters.
- deleted 4y ago[deleted]
- fernandotakai 4y agoat the end of the day, i work to make customers productive and happy, so the perfect commit is the one that moves the product towards that goal.
- Salgat 4y agoWhich includes a sensible (but not excessive) approach to avoiding technical debt that inhibits future functionality and feature generation.
- simonw 4y agoProbably should have mentioned that in the post: a benefit of working this way - in particular bundling tests in the same commit as your implementation - is that it makes it much safer to implement continuous deployment. Many of my projects that use this style of commits are configured so that code is deployed to production every time a commit passes CI.
- mejutoco 4y agoInstead of downvoting I am giving my opinion: if you really believed this you would not be using version control. P.S. I am assume you do, since you mention commits.
- Supermancho 4y ago> if you really believed this you would not be using version control. > P.S. I am assume you do, since you mention commits. That's circular logic, at best. This is about the label given to "perfect" commit(s), for which someone has made an arbitrary qualitative list of attributes. The GP has a different qualitative list.
- js2 4y agoPerfect commits are a bulwark against technical debt: https://www.infoq.com/articles/business-impact-code-quality/ https://www.infoq.com/articles/business-impact-code-quality/ https://news.ycombinator.com/item?id=33372016 https://news.ycombinator.com/item?id=33372016 The extra time spent crafting a perfect commit today will save 10x that time in the future. Your future self will thank you, and if not your future self, then I will, when I inherit your code.
- psychoslave 4y agoI very rarely check the repository history, even less to find an answer in how some buggy behavior was introduced. At most I'll git blame, search the issue repository and see if I can chat with the concerned people. Understanding the current relevant code and what need to be done is basically always sufficient to do the job. Digging into history, while potentially very interesting, never helped to reduce the time to resolve anything in my experience. If the code is a mess, the history will be exponentially so. If the code base is clean and well documented, you might more likely have a great set of "perfect commits" that you will never need.
- deleted 4y ago[deleted]
- quickthrower2 4y agoHistory is useful because blame often get’s it wrong. So it is a manual blame.
- grogers 4y agoWriting good code and writing good commits definitely clusters together. It's part of a general pride in quality of work, organization, and planning. Going back into the commit history can be useful to figure out if something suspicious was introduced intentionally or if it was just a mistake. Beyond about 3-6 months, the author will generally not have any context to remember small code details, so leaving breadcrumbs for your future self and team can be nice.
- js2 4y ago
- willm 4y agoGreat article. I’d like to quote it in a GitHub issue template. I struggle with “a single focussed change”. As my coworkers will attest. When working on new features rather than bugs, I find it hard to say when one feature ends and another begins. Something I need to work on!
- quickthrower2 4y agoTry to say it before coding, and probably the team should help with chunking it down. Sometimes a thing cannot be chunked down more without silly inconvenience so keep that in mind.
- simonw 4y agoOne thing that works for me here is to try and split the work into changes that could be shipped to production independently of each other.
- ivix 4y agoWhen in a serverless environment it's easy to get into a situation where you need to commit to deploy and test anything. Then git squash is essential, unless you're the only developer.
- ecshafer 4y agoCommit basically doesn't matter to me, I think in the terms of PR. I can make 100 commits or 1, it doesn't matter because when I merge I squash them into a single commit that encompasses everything. There are some exceptions, as splitting a large merge into several smaller merges can help a lot, for example adding a database column in a pr, then adding in a separate merge usage of that column. In terms of commits, the commit message should be a good summary of what is there. In terms of a PR there should be several things. One is obviously tests present. The next is a what, why and a how, which should be explanations of why you are doing it, what the purpose is, how you are doing. Finally I think there should be a descsription of how this should be tested manually.
- simonw 4y agoTotally agree - if I'm working on a larger change I'll usually do that in a branch, which ends up as a PR which I then squash-merge into a "perfect commit" as described in the article.
- neon_electro 4y agoThis is why I now love GitHub's "squash & merge"; it accomplishes so much of the ideals laid out in this "perfect commit" article.
- CuriousCosmic 4y agoI have to disagree. Mainly because I care what the contents of the branch were after the merge when I have to go back and figure out why a particular error is occurring. Mainly my workflow is: 1. Commit often with moderately useful commit titles/texts. 2. Rebase -i prior to pushing to remote. During rebase, squash/fixup together relevant commits and write succinct commit titles with useful commit texts. Then push. 3. Rebase -i again at the end of the PR to guarantee everything is coherent and that each commit that makes it in the merge at least builds and passes existing tests (i.e. that functionality before the branch isn't broken in the branch). 4. Merge into master. Merge commit should include the PR info (like PR text contents) in the merge text if at all possible. 5. Forget. Maybe move to a new git host. The years later when I identify a bug I can just: 1. Put together a reproducible example. 2. Git bisect --first-parent (only top level commits/merges) to identify the merge where the bug was introduced. 3. Git bisect the merge itself to identify the exact commit that introduced it. 4. From there I can determine the context of hows and whys behind the bug being introduced, identify a possible solution, and evaluate any process changes that could have prevented this bug from being introduced elsewhere in the project.
- Waterluvian 4y agoRaise your hand if commits are mainly just a way to save progress. It can’t just be me. I appreciate that needs differ between projects. In some public project I’d be more disciplined. But at work I just commit like a madman and collapse them all automatically upon merge.
- ISL 4y agoThe key world is "mainly". If things go wrong, you haven't just saved progress, but also saved history. That distinction is powerful.
- Waterluvian 4y agoIndeed. A clean history can be helpful. And this is certainly context specific. In my experience it hasn’t been as useful as the cost to do so, so I’ve relaxed a bit on making my commits carefully.
- deleted 4y ago[deleted]
- harryvederci 4y agoFor work it's different, but for my side project: $ git log --pretty=oneline | wc -l # Total amount of commits. 1369 $ git log | grep '^ \.$' | wc -l # Count commits with a message of "." 902
- deleted 4y ago[deleted]
- tkiolp4 4y agoHere. I have a colleague obsessed with the “perfect” commit, with rebase instead of fast forward merges and what not. Can’t stand it. I do care about writing a good summary commit title that includes the Jira issue number that links to a well description of the feature/issue at hand.
- cratermoon 4y ago
- vsviridov 4y ago"Link to issue for context" Just no... Why would you decouple the change from its context? Just add all the relevant information to the commit message itself, so it's preserved. I follow my friend's approach which works really well. https://yrashk.medium.com/solving-problems-one-commit-at-a-time-f0c56bbda7a0 https://yrashk.medium.com/solving-problems-one-commit-at-a-t... Too many a times I had to do code archeology to encounter archived Jira or some old space I don't have permissions for, that was originally migrated from GitHub issues and all the ticket numbers are in complete mismatch.
- simonw 4y agoYou can't put screenshots in a commit message. You also can't update a commit message after you've pushed it. Agreed though that you shouldn't work like this if you can't trust your organization to reliably archive your issue threads!
- Salgat 4y agoBoth Github and Bitbucket support all of that in the PR, so if necessary, update your PR with additional comments/information. When I'm looking at a change, I always go back to the PR anyways since it provides discussion relevant to the change.
- simonw 4y agoYeah I sometimes use a PR in place of an issue thread for this kind of thing, because PRs support the exact same comment system that I find so valuable in issues.
- Izkata 4y ago> You can't put screenshots in a commit message. Now I'm wondering how big a git commit message can be and if a base64-encoded image would fit... > You also can't update a commit message after you've pushed it. Check out "git notes", it lets you add more to a commit message without changing the hash. No idea how it interacts with things like gitlab/hub.
- deleted 4y ago
- 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 agoMost 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.
- g051051 4y ago> Our job as software engineers is not to write new software: it’s to apply changes to existing software. Well, I could stop reading right there.
- simonw 4y agoI probably should have expanded that point: I was trying to be pithy. What I meant is that we spend 95% of our time making changes to software - adding new features, fixing bugs etc. Starting a new project from scratch is something we might do a few times a year at most, but changing an existing project is a thing we do every working day.
- g051051 4y agoAdding new features is writing new software in my book.
- unionpivo 4y agoMost developers add new features by modifying/adding to an existing code/repo most of the time. Hell even when you create new project, a lot of development environments provide basic scaffolding, that you then modify (or sometimes remove 95% of).
- cratermoon 4y agoWhat do you call writing -2000 lines of code? https://www.folklore.org/StoryView.py?story=Negative_2000_Lines_Of_Code.txt https://www.folklore.org/StoryView.py?story=Negative_2000_Li...
- g051051 4y agoI call it "LOC is a terrible metric".
- khpart 4y agoIt's Python, which is a churnfest by design. Other communities have this problem to a lesser degree.
- wellpast 4y agoGoing to express a counterpoint. Maintainable/malleable software is mostly to due with the architecture of the code at any given point in time, not the sequence of commits that got it there. (I'll take all N,000 commits collapsed into one with a message "Stuff" if the code is well-articulated than a series of perfect commits that culminate into a highly coupled volatile system.) Furthermore, I'll posit that these "perfect commits" have a tendency to trend toward overall bad code architecture. Primarily because the attention flashlight is being shined on the wrong then (the delta as opposed to the resultant codebase). In the course of working on a system I'll often earmark code decoupling/cleanup as part of a commit. Or move to get cleanup in quickly so that my general feature/value delivery is achieved. But processes that focus attention on commits (like this "perfect commit" and also formal code review processes) discourage this kind of continuous cleanup/refactoring that is the only way to get to good code.
- quickthrower2 4y agoThat is the perfect merge commit onto trunk/main. Branch commits can be chaotic if needed. The commit is then the unit of “walkawayability” a checkpoint where if thing get screwy they are happy to revert to.
- thom 4y agoSomehow I’m really wary of all the energy that goes into source control workflows and commit messages. It’s all meta-information and the only time it really matters is when something has gone catastrophically wrong. If you genuinely have to go looking at the history of a codebase to find out why something weird has happened, that feels like a codebase crying out for a better structure. New features shouldn’t be major surgery, they should be instances of established abstractions. I’m very interested in languages that make that modularity easier but if you can’t delete your entire Git history with no negative consequences that just seems like a disaster to me, on both an individual and industry-wide scale.
- cratermoon 4y ago> the only time it really matters is when something has gone catastrophically wrong Or in other words, it matters most when it's most needed and the recovery process is glad to have them. Think about the airline industry and how many times the causes of an accident have been found in the months-old maintenance records of an aircraft, or in an examination of pilot training from last year. Now imagine throwing away all the information that could have led to finding a cause and putting in place mechanisms and practices to prevent a recurrence. This is how the software industry continues to stumble over the same problems that were known and described in the 70s.
- thom 4y agoI don’t think it’s _necessary_ when something goes wrong. I think it’s a sign of a process going wrong (which is just as likely as your commit message process going wrong). If you can’t work out why a piece of code looks the way it does or why it even exists, the fix isn’t better commit messages, it’s better code.
- thom 4y agoI want to be clear I’m not just being a curmudgeon here. There’s been interesting, old work in the OO world about capturing use cases more explicitly in your model. I think some work around micro front-ends is promising. Anything that lets you compose new work in a modular, clear, explicit way is very interesting. And I think that’s the path we should take as an industry, rather than running git blame to understand why a particular case in a switch statement exists. At the very least, everything useful in a commit message could be a comment in the code, but even that seems weak to me.
- J-_-_b 4y agohere's 95% of all of my commit messages: "wip"
- ChrisMarshallNY 4y agoI will often paste a line from the CHANGELOG.md into the commit. We used to use Perforce, which forced you to write a commit message. One of my employees used to write "asdf". It got a bit old. I didn't care that much, myself, as he was responsible for maintaining his own code, and he did fine, there. The Japanese hated it, though, and it probably played a big part in his getting laid off. I learned a big lesson, there, and insisted on my employees being more circumspect, after that.
- DangitBobby 4y agoI think there are two things in tension here. VC is primarily useful to help make sure you don't lose work and can merge separate threads of work into one place. In distant second is its ability to communicate those changes being made. That's also probably happening on numerous other places, like your issue tracker, documentation, whatever. Anyway, if I'm in the middle of something that doesn't really form a complete coherent change but also represents work I don't want to lose... You might get useless commit messages. Useful commit messages are valuable, but so is the ability to actually incrementally change and back up your code. As an aside, that's why I think blocking pushes to remote due to failing tests/linter issues/basically any reason is misguided.
- ChrisMarshallNY 4y agoYes, that makes a lot of sense. I like to have many small commits, as opposed to one big one. However, I’ll often defer a commit, to avoid “breaking the build.” I’ve come to avoid branching, if at all possible, using tags, instead. That works for me, as I generally work alone, but it does not work for a team. In that case, we need working branches, and a stable mainline. In my experience, commit comments are almost worthless, except as “mnemonics.” I tend to use diff views, instead, to figure out commits.
- 4y ago
- donatj 4y agoI am a firm believer that a commit should rarely be more than a couple minutes of work. When I go to git-blame, I want the commit message to be the why of this specific change. When I git blame and find a commit that's thousands of lines I wonder why we're even using git at that point and not just saving zips. The proponents of PR Squashes irk me. You're losing all the value of git. In the future when I'm hunting down a problem I almost never care about what feature or fix this was a part of - e.g. the PR - I care entirely about the context of the developers mind when he committed that specific line of code. In the rare case you do actually care what PR a commit is from, GitHub's search will tell you.[1]. There's no need to put that information in a commit at all. I was recently hunting down the reason for a single ! casting a string to a bool. The blame on the file lead to a large commit with details about the project, but nothing about why that specific line of code was changed. Was it an accident? Did it serve an actual purpose? I might never know. Commits are cheap. Blames are easy. There's zero need to try to keep your tree "looking nice". 1: https://github.com/donatj/CsvToMarkdownTable/search?q=f4c167a1cb391b80fcff0f071b9570a6995f9bbc&type=issues https://github.com/donatj/CsvToMarkdownTable/search?q=f4c167...
- simonw 4y agoIs this example too large or about the right size for you? https://github.com/simonw/sqlite-utils/commit/ab8d4aad0c42f905640981f6f24bc1e37205ae62 https://github.com/simonw/sqlite-utils/commit/ab8d4aad0c42f9...
- donatj 4y agoThat's probably fine, honestly. I'd maybe take a little more context in the message, but I certainly write messages like that myself. It's always later when I'm looking into problems that I want more context. I spend a lot of time hunting down problems. Half the time I caused them. I know tone/angle of commit messages is an entirely separate bag of cats that people have strong opinions about, but I find the tone strange. I generally fond of commits that state what the commit does. Something along the lines of "Adds optional table support"
- 4y ago
- glacials 4y agoAuthor might be interested in Git notes (`git notes --help`). Notes are arbitrary text content added to commits that don’t affect the commit’s identity, so they can be amended without rewriting history.
- jonnycomputer 4y agoIs there a way to add only certain lines of a file to a commit? Sometimes it'd be nice to say, "only these changes" make it to this commit, while "those changes" will be for another. Easy enough to do when they happen to be in different files, but sometimes that doesn't work out.
- simonw 4y agoYeah, you can do that with "git add -i" - it's not got a great interface but once you've learned how to use the "patch" and "split" commands you can generally craft commits with just specific lines pretty effectively.
- iib 4y ago`git add -p` should do it. git works great by "patches", not necessarily by "files", so what you are saying is supported out of the box really well.
- 9dev 4y agoIf you use an IntelliJ IDE, they have this— I frequently select just a few lines in a diff viewer and commit selectively what is logically coherent. Not affiliated, just a big fan.
- Noumenon72 4y agoYup, this is awesome. Just flit from one change to the next with Opt-Down Arrow and uncheck the ones you don't want to commit.
- other_herbert 4y agoIt also will track changes you don’t want… like if you have something you’ve changed for testing that can be kept in a separate change list (I call mine “ignore-for-now”) and the n future changes to that file would be in the regular changes, just minus the other stuff… also not affiliated, another fan
- deleted 4y ago[deleted]
- furyofantares 4y agoI work on small teams making video games. The hard part is figuring out what to make. The faster you can see your ideas play out in game and process feedback, the better. And any given piece of leaf gameplay code, at the time of being written, has a decent chance of being rewritten or deleted. Usually engine/tooling code doesn't work like this, and there's also systems in between the engine/tooling and the gameplay code that are written to make gameplay code very fast to write, and those in-between systems also don't get iterated on like this. But most of the time is spent figuring out what to build by building something and iterating on it, and the perfect commit sounds like an excellent way to not get anything done in this context. I'd like to make 5-10 changes before lunch, play or spectate a playtest in the afternoon, and process feedback afterwards, as well as fit in a design discussion that's not necessarily about anything that's currently being iterated on.
- simonw 4y agoThis sounds to me like what I think of "prototyping" in my own process. When I'm prototyping I'm often not working with version control at all - or if I need to track changes over time I'll work in a branch (or sometimes even just a GitHub Gist, which is effectively a cheap separate repo). Once I've prototyped my way to a design that I like, I'll craft a proper commit with tests that captures the new design.
- sreevisakh 4y agoThe perfect commit is useful only when you're ready to publish. Development can be chaotic with all the half-done or possibly-wrong code. You don't need to worry about all those standards while you're still developing. The perfect commit is then crafted out of the chaotic development branch by editing the history. I keep the original development branch alive for reference, while the crafted commit is submitted to the maintainer.
- mason96 4y agoThe perfect commit = links to his own PRs Okay sure
- beachy 4y ago> Without tests, there’s a very strong possibility that your change will have broken some other, potentially unrelated feature. [...] > This is why I start every single one of my projects with a passing test. It doesn’t matter what this test is—assert 1 + 1 == 2 is fine! These two statements do not add up.
- lostcolony 4y agobadum-tsh That said, I think he just means "do the work to get tests in place, and build the habit of running them as part of your development cycle", even if, when starting, what you're running isn't helpful. The idea being that building "write a test" "run the tests" into your iterative loop, from the beginning, is a worthwhile practice.
- BlargMcLarg 4y agoIt's half work until those tests actually test something of value. We all know what happens with half-work in the long run, and it certainly isn't 'they build habits towards full work'. That's before considering even if the tests do test something, most code tests written are easily improved upon garbage.
- simonw 4y agoThey add up if you consider the text in between them: "Adding a new test to a project with a lot of existing tests is easy" My point here is about ensuring you have a test suite from the very first commit to a repo, so you have an obvious place to add tests to in further commits.
- rendall 4y agoIf one is working in a team, and the team does code review before committing to master, then tests can be part of the code review. The most stable code bases I have ever worked with come with teams who will reject a pull request with inadequate tests.
- _gy5c 4y ago``` 0 lines added 1 line removed ```
- superdug 4y agofull stop ... if you want my commit to be perfect ... make a unit test I can run on my PR. Meet my need first, and I will automatically meet yours.
- andirk 4y ago1) Write commit message. 2) THEN start doing work. If you get up for a spliff break, 1st thing after sitting back down is re-read commit message. Stay on track. 3) Stage files that are kempt, like a mini commit within the commit. 4) Once all files are staged, look at them and look at the message to make sure you have mentioned all that changed, including sometimes _why_. 5) Commit! But don't always push! Only push if you really like what you did. 6) Repeat. Squash similar commits together. 7) Rebase in master or merge in master. 8) Push! 9) Repeat! 10) PR! Your commits will read like a story of the what and sometimes the why. PRs go smoothly. All is well. Lots of steps but it takes very little extra time.
- brian_cunnie 4y ago> An issue is more valuable than a commit message Watch out! An issue is more ephemeral than a commit message: The issue might not always last, but the commit message will. If, say, a project is re-hosted from GitHub to an internal GitLab instance. Or maybe the original project dies, and all the active work is done on a fork. In such cases, the original issues are gone, but the commit messages stay. So put everything that's important into the git commit message. Don't assume the issue will always be there. I learned this the hard way when the company I worked at used something similar to GitHub issues (Pivotal Tracker stories) to record the important background to a commit, which was great until the story was purged (because, say, the Tracker project was deleted).
- 8n4vidtmkvmk 4y agoits worth porting the issues to the new platform. i ported bitbucket to GitHub which was annoying because you can't choose the bug # so you have to import then in order and get it on the first try.. but at least everything lines up now
- Macha 4y agoIn larger companies this is rarely your decision to make and in three different issue tracker migrations I've seen the team responsible for maintaining the issue tracker instead to keep the old tracker in a read only state until they either have to renew the vendor contract or make security updates, at which point the issues go down the drain. This may all have happened before you joined, so it's not likely you could have done the migration yourself (and the security team may have disabled generating API keys which automated migration tools need, anyway)
- 8n4vidtmkvmk 4y agoWell... Whoever was in charge of those decisions made bad choices then I've done it twice now in tiny companies. Only takes a couple days to hack together a script
- Izkata 4y ago
- immy 4y agoReformatting mixed with real changes, woooof
- irrational 4y ago> Our job as software engineers is not to write new software This can’t mean what the plain reading would suggest it means. I mean, I can’t be the only one writing new software all the time, can I? So, what does it actually mean?
- simonw 4y agoSee this comment: https://news.ycombinator.com/item?id=33388466 https://news.ycombinator.com/item?id=33388466 It was a clumsy way of indicating that we very rarely start a new project from scratch - if we are building a feature it's almost always adding to an existing project.
- manunamz 4y agoThis is a nice write-up. I agree with other comments here too, which mention not necessarily needing to hit all points on this list. If working alone, or quickly prototyping, they may not be strictly necessary. It's about trade-offs: The more people involved or the longer one goes without re-visiting a project, the more important these bullets become. If there isn't a pre-established standard, it's useful to run a mental "commit hook" that evaluates the usefulness, or future likelihood of usefulness, of these items.
- swyx 4y ago> I use these cookiecutter templates for almost all of my new projects. They configure a testing framework with a single passing test and GitHub Actions workflows to exercise it all from the very start. this looks pretty handy and i feel like if anyone from @github is reading this it could maybe be built in to make the templates functionality a bit more useful out of the box
- rendall 4y agoOne benefit of squash-commits to master/main is in continuous integration. If the commit needs to be reverted because it introduced a bug into production, the reversion is relatively easy to do. With an entire history, especially with later commits, finding the buggy commit can be a nightmare.
- drawfloat 4y agoIt’s a shame you can’t collapse commits when merging a branch - generally see a the single commit for the merge, but can expand to view the commits that were collapsed if you ever need a fine grain review in the future.
- uwemaurer 4y agoTo me it is most important that the commit is focused only on one thing, and not mix any unrelated changes together. We develop a Rust based tool HighFlux [1] which simplifies/automates working with git. In this workflow you create a feature branch for every feature you work on and it automatically commits all changes to this branch. After code review the branch gets merged as a squashed merge to have it in a single commit in the history. 1: https://www.highflux.io/ https://www.highflux.io/
- kalekold 4y agoThere had to be a rust ad in here somewhere.
- sreevisakh 4y agoThe ad is about a git tool (hiflux) that happens to be written in Rust. That is perfectly relevant in this context. Rust is also a good language to write such tools (as is Go). I understand why Rust evangelism can be a bit tiring. But the opposition to it shouldn't try to imitate the same quality.
- m000 4y agoHow do you keep you commit focused on one thing if you squash? Often, before you reach to the point where you can make the change you want, you need to make side-changes which are not a strict part of the feature you're building. These should ideally be reviewed separately.
- uwemaurer 4y agoI agree this happens quite often. Since Highflux automatically commits changes to the current branch it is extremely easy to switch to a different branch with just one click (or CLI command). (so no stashing / dealing with untracked files is needed) Then you can implement the side change separately and then switch back again to your first feature branch. Those two feature branches are then unrelated, we are planning to add stacked changes in a future version.
- febeling 4y agoThis depends on so many variable that I don't believe there's one perfect commmit. E.g. it depends in the lifecycle stage of the project. Is it just you figuring something out, or are hundreds of thousands of people depending on your work with their livelihoods? The first probably deserves the kinds of restraint that Op wants to see. Whereas you would terribly stifle you creative flow if you were to write docs for your explorative work in the unknown.
- penguin_booze 4y agoMy rule of thumb is to size and structure commits so that they're worthy of cherry-picking. This is blame-friendly, too. I find it frustrating when `git blame` tells you "review comments".
- deleted 4y ago[deleted]
- kingkongjaffa 4y agoas a PM how do I write the perfect feature/bug issue?