Add a first draft of Changelog Guidelines.

Moya / contributors

How the Moya org handles contributions

Other

57 stars 11 forks source link

Add a first draft of Changelog Guidelines. #16

Closed sunshinejr closed 7 years ago

sunshinejr commented 7 years ago

Wasn't sure if it's the right place, but yeah. I also wasn't sure with the from keyword before the tag of a person who did a change. We may consider alternatives like by or just a -.

Follow-up steps (after merge):

[ ] Change Rakefile's release route accordingly (name/release date)
[x] Update Danger to point to this documentation
[ ] Slowly update old Changelog entries

Let me know what do you guys think!

ashfurrow commented 7 years ago

@SD10 I'm not sure I understand you – which section headers?

SD10 commented 7 years ago

Sorry @ashfurrow it was the first thing I wrote this morning and I wasn't clear enough.

I think we should paraphrase the key components of the keep a changelog link and then link to the full version at the end of the document.

This would allow our document to stand alone (the user can view the link for more details).

Types of changes

Added for new features.
Changed for changes in existing functionality.
Deprecated for soon-to-be removed features.
Removed for now removed features.
Fixed for any bug fixes.
Security in case of vulnerabilities.

ashfurrow commented 7 years ago

Ah, that makes sense 👍 I agree.

sunshinejr commented 7 years ago

Good idea! Should we also copy the basic guidelines as well?

Guiding Principles

Changelogs are for humans, not machines.

There should be an entry for every single version.

The same types of changes should be grouped.

Versions and sections should be linkable.

The latest version comes first.

The release date of each versions is displayed.

Mention whether you follow Semantic Versioning.

SD10 commented 7 years ago

@sunshinejr I was hesitant to add that section because it felt more "philosophical" but on second thought I think it would make a good addition. ie.) "The same types of changes should be grouped."

Two more thoughts:

We should mention that we always keep an unreleased section at the top
Once we merge this, we can have Danger link to this file when it throws a CHANGELOG warning

sunshinejr commented 7 years ago

I agree with both, gonna update the PR soon.

sunshinejr commented 7 years ago

Also, I don't really feel the from keyword before the contributor - how about changing this one to simply -?

SD10 commented 7 years ago

At IBAnimatable we use the format: [#PR] by [@user]

sunshinejr commented 7 years ago

Cool! I've made changes discussed here, let me know how it looks :)

sunshinejr commented 7 years ago

Thanks guys!

BasThomas commented 7 years ago

Sorry I am late on this, but was just reading the changelog on the v10 beta 1, and I found reading it very confusing.

I skimmed only the bullet points - not the headings - making it feel like words like "added" were wrongfully omitted.

Therefore I'd like to propose the following change in format:

# Added

- Added a
- Added b
- *Breaking Change* Added c

Instead of the current

# Added

- a
- b
- *Breaking Change* c

This would be a bit more verbose, but wouldn't "break" skimming only the bullet points.

cc @sunshinejr @pedrovereza @ashfurrow @SD10

sunshinejr commented 7 years ago

I agree 👍

SD10 commented 7 years ago

Unfortunately, I agree :( I’ve been using the same guidelines on another project and I find it really difficult to communicate the omission of the first word

_{Sent with GitHawk}