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

connorjs commented 10 months ago

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 :memo: 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?

[X] 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

[X] Follow our Code of Conduct
[X] Read the Contributing Guide.
[X] Check that there isn't already an issue requesting the emoji.

connorjs commented 10 months ago

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 10 months ago

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 🌞

carloscuesta / gitmoji