Write history, keep a diary (PHP-WVL meetup)

Nowadays developers, and others, have the habit to use Git or other version control systems when writing software. While the benefits of this are mostly seen by means of pull/merge requests, easy "undo" functionality, team collaboration and others, the real benefit is history. When did we change this piece of code, and more importantly: why?

By using clever commit message and branch strategies, you can reconstruct the way your or your colleagues' brain was thinking a year ago! It will help you pinpoint the exact ticket where a client requested a specific change and by who it was sanctioned.

Start keeping a diary today, and write history!

Transcript

1. WRITE HISTORY, WRITE HISTORY, WRITE HISTORY, WRITE HISTORY, WRITE HISTORY, WRITE HISTORY, WRITE HISTORY, WRITE HISTORY, KEEP A DIARY KEEP A DIARY KEEP A DIARY KEEP A DIARY KEEP A DIARY KEEP A DIARY KEEP A DIARY KEEP A DIARY Jachim Coudenys Jachim Coudenys Jachim Coudenys Jachim Coudenys Jachim Coudenys Jachim Coudenys Jachim Coudenys Jachim Coudenys jachimcoudenys@gmail.com jachimcoudenys@gmail.com jachimcoudenys@gmail.com jachimcoudenys@gmail.com jachimcoudenys@gmail.com jachimcoudenys@gmail.com jachimcoudenys@gmail.com jachimcoudenys@gmail.com @coudenysj @coudenysj @coudenysj @coudenysj @coudenysj @coudenysj @coudenysj @coudenysj
2. CODE
3. The primary goal of a software developer should be to communicate their intent to future developers — Louise Crow / @crowbot
4. VERSION CONTROL SYSTEM
5. Re-establishing the context of a piece of code is wasteful. We can't avoid it completely, so our efforts should go to reducing it [as much] as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator. — http://who-t.blogspot.be/2009/12/on-commit-messages.html
6. RICHARDSON MATURITY MODEL
8. LEVEL 1
9. ATOMIC COMMITS Small One problem / case at a time
10. COMMIT MESSAGES What and why instead of how Use subject and body (if required, small changes don’t need a body)
12. GIT LOG commit fe41f5836552517da3d5cff2a970d6d0a6a8f06c Author: Russell Yanofsky <russ@yanofsky.org> Date: Wed Dec 7 15:41:56 2016 -0500 Remove undefined FetchCoins method declaration ...
13. GIT LOG --GREP "BUGFIX" commit 6aa28abf53ef4694692474b4a3b0a8fa7559b50b Author: Pieter Wuille <pieter.wuille@gmail.com> Date: Sat Jun 25 19:17:45 2016 +0200 Use cmpctblock type 2 for segwit-enabled transfer Contains version negotiation logic by Matt Corallo and bugfixes by Suhas Daftuar. ...
14. GIT LOG -S TEST commit 2efc43874cedde7e022ac8f1051c7984331543fa Author: Pieter Wuille <pieter.wuille@gmail.com> Date: Fri Dec 2 19:24:23 2016 -0800 Align struct COrphan definition diff --git a/src/net_processing.cpp b/src/net_processing.cpp index 747167264..5a415cabb 100644 --- a/src/net_processing.cpp +++ b/src/net_processing.cpp @@ -50,6 +50,7 @@ struct IteratorComparator }; struct COrphanTx { + // When modifying, adapt the copy of this definition in tests/DoS_tests. CTransaction tx; NodeId fromPeer; int64_t nTimeExpire; diff --git a/src/test/DoS_tests.cpp b/src/test/DoS_tests.cpp index 1a818a575..a8c3c4ebb 100644 --- a/src/test/DoS_tests.cpp +++ b/src/test/DoS_tests.cpp @@ -29,6 +29,7 @@ extern unsigned int LimitOrphanTxSize(unsigned int nMaxOrphans);
15. LEVEL 2
16. PURE ATOMIC COMMITS Code formatting ALWAYS in separate commit! Create different commits from a “dirty” workspace git add -p
17. REWRITE HISTORY IF NECESSARY Git is distributed private flexible git commit --amend git rebase -i
18. GOOD COMMIT MESSAGES Length Do you like reading rambling paragraphs on one long lin 50 characters 72 characters wrap Stop using git commit -m Reference to tickets, pattern pages, manual pages, etc.... with full urls
19. COMMAND LINE: LENGTH git log --pretty=oneline git rebase --interactive merge.summary git shortlog git format-patch, git send-email reflogs gitk Github, etc...
20. COMMAND LINE: GRAPHS Network tab in Gitlab, Github, etc... $ git log --graph --oneline * 76fcd9d50 Merge #9309: [qa] Wallet needs to stay unlocked for whole test |\ | * 9359f8ad3 Wallet needs to stay unlocked for whole test * | a1dcf2e10 Merge #9240: Remove txConflicted |\ \ | * | a874ab5cc remove internal tracking of mempool conflicts for reporting to wallet | * | bf663f8e9 remove external usage of mempool conflict tracking * | | d38b0d7a6 Merge #9307: Remove undefined FetchCoins method declaration |\ \ \ | * | | fe41f5836 Remove undefined FetchCoins method declaration * | | | 815640ec6 Merge #9295: [Wallet] Bugfix: Fundrawtransaction: don't terminate when keypool is em |\ \ \ \ | |_|_|/ |/| | | | * | | 1a6eacbf3 [QA] add fundrawtransaction test on a locked wallet with empty keypool | * | | c24a4f598 [Wallet] Bugfix: FRT: don't terminate when keypool is empty * | | | 72bf1b3d0 Merge #9303: Update comments in ctaes ...
21. COMMAND LINE: MERGE BUBBLES
22. LEVEL 3
23. SUPERB COMMIT MESSAGES Answer some basic questions Why is this change necessary? How does it address the issue? What side effects does this change have?
25. SUPERB COMMIT MESSAGES commit 0fdf810d267928b4c26a2e2cbb8c02b79e7b0ccb Author: Wladimir J. van der Laan <laanwj@gmail.com> Date: Fri Oct 28 14:15:46 2016 +0200 Change default confirm target from 2 to 6 Recent discussion (in IRC meetings, and e.g. #8989) has shown a preference for the default confirm target for smartfees to be 6 instead of 2, to avoid overpaying fees for questionable gain. 6 is also a compromise between the GUI's pre-#8989 value of 25 and the bitcoind `-txconfirmtarget` default of 2. These were unified in #8989, but this has made the (overly expensive) default of 2 as GUI default.
26. SUPERB COMMIT MESSAGES Imperative "Fix bug" vs "Fixed bug" or "Fixes bug" like git merge and git revert If applied, this commit will your subject line here Link to previous commits (like “git revert” does)
27. POWER COMMITS: HOOKS Automate stuff Closing issues via commit messages Prepend ticket number from branch to message Validate commit message format
28. ISSUE NUMBERS
29. Every line of code is always documented — http://mislav.net/2014/02/hidden-documentation/
30. COMMAND LINE: WHO'S TO BLAME? $ git blame README.md 202f612a41 (Pavel Janík 2015-10-05 21:20:43 1) Bitcoin Core integration/staging tree c8af33aa75 (Wladimir J. 2013-12-17 11:50:26 2) ===================================== 20d5945505 (Colin Dean 2012-12-12 21:27:58 3) 5a0823a09b (randy-waterh 2014-08-26 21:10:52 4) [ b07b103e8a (BtcDrak 2016-01-15 07:45:39 6) https://bitcoincore.org 20d5945505 (Colin Dean 2012-12-12 21:27:58 7) 20d5945505 (Colin Dean 2012-12-12 21:27:58 8) What is Bitcoin? 20d5945505 (Colin Dean 2012-12-12 21:27:58 9) ---------------- ...
31. SUMMARY Use a project/company/etc... wide commit format and document it! Style Content Metadata Ditch Git GUIs and start using the command line Read your code (see next) Split up commits (atomic commits) Don’t do "end-of-day" or "code drop" commits Rewrite history if necessary
32. THANK YOU http://legacy.joind.in/talk/view/20005