Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add Changelog Guidelines #2352 #2358

Merged
merged 5 commits into from
Sep 13, 2021
Merged

Add Changelog Guidelines #2352 #2358

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2e842a2
Add Changelog Guidelines #2352
IhsenBouallegue Sep 6, 2021
65c218e
Correct the When? #2352
IhsenBouallegue Sep 6, 2021
ea6aff6
Improve description #2352
IhsenBouallegue Sep 13, 2021
d0c2923
Merge branch 'main' into docs/2352/create-changelog-guidelines
IhsenBouallegue Sep 13, 2021
2ae1465
Add changelog entry #2352
IhsenBouallegue Sep 13, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
41 changes: 41 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,3 +79,44 @@ To unify the appearance of all commit messages we only accept commit messages us
- Name the PR like its branch name (e.x. `Tech/123/my branch name`). The name is usually created by GitHub automatically
- Add the correct labels
- The PR Assignee is only used by the reviewer to see who is reviewing it

## Changelog Guidelines

###Why should you we write a changelog?

- A changelog is vital for the developers to keep track of their work. But most importantly now that it appears on every version update to every user, we should make sure that it is also user-friendly. And for that, we need guidelines to help us.

###When should you add to the changelog file?

- You should only add a changelog entry after the merge (or approval) of your feature/fix not before.
IhsenBouallegue marked this conversation as resolved.
Show resolved Hide resolved
(so that we ensure in every release the entries in the Changelog match the changes in that version)

###How should you format a changelog entry?

- [Description of what you changed] [Link to the pull request]
[One picture (specify the width and/or height)]<br/>
Example:<br/>
`- Add a changelog dialog with the latest additions to CodeCharta that appears on version update ([#1315](pull-request-linkl)) <img src="image-link" width="350px">`
The image should always have a width and/or a height attribute.
Example: width=”500px”

###How to write a good description?

- The description should be precise and short. Please keep it in one sentence (Max. 2).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ruben suggested a while ago to describe the behavior of (for example) a new feature in detail. I like this idea and personally would keep it instead of writing just one sentence :)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense from a developer point of view. But as a user, I want a straight to the point description. What I mean is the changelog can give you a quick glance on something. If one wants to understand the details, they can click on the link for the Pull Request/Issue/documentation. That's what I noticed at least from researching changelogs of other projects.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally, as a User I would be happy about tipps regarding the usage of the new feature. Therefore I wouldn't restrict the changelog description to be as short as possible. What do you think about something like this: "The description should be precise and short to provide the user with all neccessary information. If it makes sense, add some precise notes about the usage of the new feature."

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That sounds good! Okay I will change it to that

- One changelog entry should describe one change.
- Avoid writing technical descriptions
- Start with a verb in the present tense
- Example: Add, Improve, Enable, Allow, Switch...
- Don’t: this feature added the ability to enable dark mode
- Do: Add dark mode
- Avoid writing ambiguous descriptions
- Don’t: Fix some UI problems
- Do: Fix the distribution bar not showing correctly
- Write in terms of features. Focus on the "what" not the "how".
- Don’t: Minify JS and CSS
- Do: Make page load faster by reducing size of JavaScript and CSS files

###Notes

- Link to the image can be copied from an image uploaded to the Pull Request
- If there are no Pull Requests associated to your change, link an issue.