carloscuesta/gitmoji

What gitmoji to use for ADRs? (a.k.a. "Does :memo: apply to all documentation?")

connorjs opened this issue · 2 comments

connorjs commented

Emoji symbol

⏺️ (if we need a new one)

Emoji code

:record_button:

Emoji description

Add/edit decision records

Describe the use case of your emoji

Some projects use ADRs (Architectural Decision Records) to record decisions. See adr.github.io.

Question: What gitmoji should I use for adding ADRs? Does 📝 apply to all documentation (which implies it would cover ADRs)?

Some more thoughts

  • I use 📝 (:memo:) for READMEs and code documentation.
  • I use 💬 (:speech_balloon:) for user-facing documentation in a website mostly, but could also use others
  • ADRs “felt” bigger than “just a README update” (or bigger enough), and I went looking to see if a specific emoji applied here.
  • I am perfectly happy to continue using 📝 for this case (I know we prefer not adding new ones), and then this GitHub issue can serve as self-documenting for ADRs.

If we want a new one, I recommend ⏺️ (:record_button:) b/c it has record in the name.

Other emojis considered

  • 🤔 (:thinking:) b/c it’s explicitly a decision (con: we already thought, whereas thinking implies active - this was my first thought though before deciding on ⏺️)
  • 🌳 (:deciduous_tree:) b/c it comes up when typing :decid for emoji selection (con: a play on (English) words only)
  • 📹 (:video_camera:) (or other recording emoji) b/c it’s recording (con: relates to movie/videos, which doesn’t relate)
  • 🧾 (:receipt:) b/c it documents our decisions (which we can view as “purchases”)

Is this use case covered by an existing emoji?

Yes ✅

Does this emoji fall into the "how" or the "what" category?

  • This proposal do not describe "how" a commit was made, but does in fact describe "what" is the contents of the commit about.

Examples

⏺️ Use MADR for recording ADRs

⏺️ Record choice of XXX for static website generation

⏺️ Document choice of XXX for static website generation

Note that “Record” and “Document” both apply, hence me being torn about new gitmoji vs using 📝.

⏺️ Update ADR-NNNN following review

Validations

connorjs commented

I use 📝 (:memo:) for READMEs and code documentation.

I just saw 💡 (:bulb:) - unsure how I never saw this before.

Add or update comments in source code.

Therefore, ADRs should probably just use 📝 and not add another gitmoji.

I’ll leave this open in case others want to chime in, but feel free to close (maintainers).

carloscuesta commented

Hey! Thanks for opening the issue ❤️

I appreciate your input and perspective on this emoji proposal. Using 📝 for ADRs, RFCs, and any technical documents makes sense to me, as it conveys the idea of documentation in a broader context.

The point about maintaining simplicity and avoiding an excessive addition of emojis is something we want to maintain for Gitmoji! Using an existing emoji like 📝 that already signifies documentation covers a wide range of use cases, including ADRs, and keeps things straightforward.

Completely agree that sticking with 📝 for ADRs is a practical and user-friendly choice. It aligns with the principle of keeping things simple and understandable.

I'll close the issue and link to this in case any other questions arise!

Have a great day 🌞

  • 👍1