Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Write history, keep a diary (jsconf.be)

Write history, keep a diary (jsconf.be)

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!

Jachim Coudenys

June 29, 2017
Tweet

More Decks by Jachim Coudenys

Other Decks in Programming

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
    JSCONF.BE 29/06/2017
    JSCONF.BE 29/06/2017
    JSCONF.BE 29/06/2017
    JSCONF.BE 29/06/2017
    JSCONF.BE 29/06/2017
    JSCONF.BE 29/06/2017
    JSCONF.BE 29/06/2017
    JSCONF.BE 29/06/2017
    Jachim Coudenys
    Jachim Coudenys
    Jachim Coudenys
    Jachim Coudenys
    Jachim Coudenys
    Jachim Coudenys
    Jachim Coudenys
    Jachim Coudenys
    [email protected]
    [email protected]
    [email protected]
    [email protected]
    [email protected]
    [email protected]
    [email protected]
    [email protected]
    @coudenysj
    @coudenysj
    @coudenysj
    @coudenysj
    @coudenysj
    @coudenysj
    @coudenysj
    @coudenysj

    View full-size slide

  2. Jachim Coudenys

    View full-size slide

  3. 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

    View full-size slide

  4. A diary is a record (originally in
    handwritten format) with discrete entries
    arranged by date reporting on what has
    happened over the course of a day or other
    period.
    - https://en.wikipedia.org/wiki/Diary

    View full-size slide

  5. Diaries undertaken for institutional
    purposes play a role in many aspects of
    human civilization, including government
    records, business ledgers and military
    records.
    - https://en.wikipedia.org/wiki/Diary

    View full-size slide

  6. The primary goal of a software developer
    should be to communicate their intent to
    future developers
    — Louise Crow / @crowbot

    View full-size slide

  7. http://heeris.id.au/2013/this-is-why-you-shouldnt-interrupt-a-programmer/

    View full-size slide

  8. http://heeris.id.au/2013/this-is-why-you-shouldnt-interrupt-a-programmer/

    View full-size slide

  9. http://heeris.id.au/2013/this-is-why-you-shouldnt-interrupt-a-programmer/

    View full-size slide

  10. http://heeris.id.au/2013/this-is-why-you-shouldnt-interrupt-a-programmer/

    View full-size slide

  11. http://heeris.id.au/2013/this-is-why-you-shouldnt-interrupt-a-programmer/

    View full-size slide

  12. http://heeris.id.au/2013/this-is-why-you-shouldnt-interrupt-a-programmer/

    View full-size slide

  13. http://heeris.id.au/2013/this-is-why-you-shouldnt-interrupt-a-programmer/

    View full-size slide

  14. http://heeris.id.au/2013/this-is-why-you-shouldnt-interrupt-a-programmer/

    View full-size slide

  15. VERSION CONTROL SYSTEM

    View full-size slide

  16. 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

    View full-size slide

  17. RICHARDSON MATURITY MODEL

    View full-size slide

  18. https://martinfowler.com/articles/richardsonMaturityModel.html

    View full-size slide

  19. JACHIM'S COMMIT MATURITY
    MODEL
    Commits Messages CLI & Tools
    Level 0 git basics
    Level 1
    Level 2
    Level 3

    View full-size slide

  20. https://git-scm.com/book/en/v2/

    View full-size slide

  21. https://git-scm.com/book/en/v2/

    View full-size slide

  22. https://git-scm.com/book/en/v2/

    View full-size slide

  23. https://git-scm.com/book/en/v2/

    View full-size slide

  24. https://git-scm.com/book/en/v2/

    View full-size slide

  25. https://git-scm.com/book/en/v2/

    View full-size slide

  26. https://git-scm.com/book/en/v2/

    View full-size slide

  27. https://git-scm.com/book/en/v2/

    View full-size slide

  28. https://git-scm.com/book/en/v2/

    View full-size slide

  29. SWAMP OF PORC
    https://xkcd.com/1296/

    View full-size slide

  30. ATOMIC COMMITS
    Small
    One problem / case at a time

    View full-size slide

  31. COMMIT MESSAGES
    What and why instead of how
    Use subject and body
    (if required, small changes don’t need a body)

    View full-size slide

  32. git log
    commit fe41f5836552517da3d5cff2a970d6d0a6a8f06c
    Author: Russell Yanofsky
    Date: Wed Dec 7 15:41:56 2016 -0500
    Remove undefined FetchCoins method declaration
    ...

    View full-size slide

  33. git log --grep "bugfix"
    commit 6aa28abf53ef4694692474b4a3b0a8fa7559b50b
    Author: Pieter Wuille
    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.
    ...

    View full-size slide

  34. git log -S test
    commit 2efc43874cedde7e022ac8f1051c7984331543fa
    Author: Pieter Wuille
    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);

    View full-size slide

  35. PURE ATOMIC COMMITS
    Code formatting ALWAYS in separate commit!
    Create different commits from a “dirty” workspace
    git add -p
    git add -i

    View full-size slide

  36. REWRITE HISTORY IF NECESSARY
    Git is
    distributed
    private
    flexible
    git commit --amend
    git rebase -i

    View full-size slide

  37. 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

    View full-size slide

  38. COMMAND LINE: LENGTH
    git log --pretty=oneline
    git rebase --interactive
    merge.summary
    git shortlog
    etc...

    View full-size slide

  39. COMMAND LINE: GRAPHS
    Commit structure
    $ 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 empty
    |\ \ \ \
    | |_|_|/
    |/| | |
    | * | | 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
    ...

    View full-size slide

  40. COMMAND LINE: MERGE BUBBLES
    Merge branch 'master' of github.com

    View full-size slide

  41. COMMAND LINE: MERGE BUBBLES
    Use rebase when pulling

    View full-size slide

  42. https://www.atlassian.com/git/images/tutorials/advanced/merging-vs-rebasing/01.svg

    View full-size slide

  43. https://www.atlassian.com/git/images/tutorials/advanced/merging-vs-rebasing/02.svg

    View full-size slide

  44. https://www.atlassian.com/git/images/tutorials/advanced/merging-vs-rebasing/03.svg

    View full-size slide

  45. COMMAND LINE: SQUASHING

    View full-size slide

  46. COMMAND LINE: SQUASHING

    View full-size slide

  47. 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?

    View full-size slide

  48. SUPERB COMMIT MESSAGES
    commit 0fdf810d267928b4c26a2e2cbb8c02b79e7b0ccb
    Author: Wladimir J. van der Laan
    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.

    View full-size slide

  49. 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)

    View full-size slide

  50. POWER COMMITS: HOOKS
    Automate stuff
    Closing issues via commit messages
    Prepend ticket number from branch to message
    Validate commit message format

    View full-size slide

  51. ISSUE NUMBERS

    View full-size slide

  52. Every line of code is always documented
    — http://mislav.net/2014/02/hidden-documentation/

    View full-size slide

  53. 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) [![Build Status](https://travis-ci.org/bitcoin/bitcoin.svg?bra
    5a0823a09b (randy-waterh 2014-08-26 21:10:52 5)
    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) ----------------
    ...

    View full-size slide

  54. git config alias.praise blame

    View full-size slide

  55. 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
    Check your impact on the commit graph
    commit merge rebase squash
    Rewrite history if necessary

    View full-size slide

  56. @phpwvl
    @coudenysj
    [email protected]
    https://www.flickr.com/photos/froderik/9355090806/
    THANK YOU

    View full-size slide