Software packages are often shipped with changelog and/or release notes. What's the difference between them? Should they be both included with release of a new version?
To directly answer your question, you can include both in your software release.
Release notes are a set of documents delivered to customers with the intent to provide a verbose description of the release of a new version of a product or service. These artifacts are generally created by a marketing team or product owner and contain feature summaries, bug fixes, use cases, and other support material. The release notes are used as a quick guide to what changed outside of the user documentation.
Conversely, changelogs are comprehensive lists of the new features, enhancements, bugs, and other changes in reverse chronological order. Changelogs usually link to specific issues or feature requests within a change management system and also may include links to the developer who supplied the change.
Yes I think you can include both on a new release.
For me the main difference is that in a release note you can explain what is new or what have changed in a more comprehensive language.
In the case of a changelog you have to add more technical details of the changes, for example with commit messages with link to the diff or PRs with links to the technical discussion.
Related
We work by the git-flow workflow and we stick to semantic versioning. Today we discussed how to handle deprecations. Two questions have arisen:
A. Semver: Is it ok to gracefully deprecate a feature in a minor release (e.g. v1.12.0)?
"Gracefully" means: The feature is still supported but a warning is shown in development environment. Support will be removed with a major release (in case of v1.12.0 with v2.0.0 or a subsequent major release).
B. Git-flow: How do you properly drop support of a deprecated feature?
Given we want to drop support for a feature in v3.0.0 while the last 2.x-release is v2.14.0. So 2.14.0 must support the feature while 3.0.0 must drop support for the feature, as any feature supported in 3.0.0 cannot be dropped before 4.0.0.
Subsequently we must remove the feature in the release/3.0.0 branch. But according to git-flow, a release-branch should only accept bug fixes.
Any advice highly appreciated!
tl;dr: One way to achieve this is to simply remove the feature on develop after the last 2.X release branch is made. Or feature flag the removal, and disable it on the first 3.X release branch. If you can't do either of those for some reason, it's still OK to do it on release.
Details:
Usually you can treat dropping this feature the same way you would treat adding a new big feature by simply merging it into develop. The only difference is that you need to make sure you get the timing right such that you don't complete the code removing the feature into develop until the last 2.X release branch is created. The next release branch that comes off of develop will have the code and will be the 3.X release. If the issue is that you don't know for certain when the last 2.X release will be, you could either wait until you do know and then merge the removal code into develop, or, consider feature flagging the removal with a config change. Then your change on the release branch whenever you create the 3.X version would simply be toggling the config.
That being said, perhaps ultimately it doesn't matter anyway:
But according to git-flow, a release-branch should only accept bug fixes.
Note there is no such thing as a Git Flow Authority which dictates what you must do. There is a popular standard Git Flow, but here I use the word "standard" to just mean "original" version that many companies use as a guideline. It is not "the" standard, as no such standard exists. I think the particular text you're referring to regarding release branches (emphasis mine):
This new branch may exist there for a while, until the release may be rolled out definitely. During that time, bug fixes may be applied in this branch (rather than on the develop branch). Adding large new features here is strictly prohibited. They must be merged into develop, and therefore, wait for the next big release.
Note even "strictly prohibited" is a (strongly) suggested best practice. There are no Git Flow Gods that will strike you down if you ever violate this rule. Besides, in your case, it could be easily argued that removing a deprecated feature on the release branch is not considered "adding a large new feature". (Even if we ignore the distinction between add/remove and new/old, perhaps the feature being removed is not "large".) Regardless, sometimes new large features do get added to a release branch, for a variety of reasons. This may violate best practices, but in the real world it's not always possible to follow best practice 100% of the time. Think of Git Flow as a guideline to work in, when it makes sense to do so. Note that Vincent Driessen specifically points out in the Note of Reflection that he didn't intend for Git Flow to become "dogma or panacea".
I am researching development in VisualFiles.
How can I use version control on the files(scripts) I have changed?
My solution so far:
Setup:
Create a folder structure within the repository according to my applications.
Update process
I will modify a file in visual files
I will then manually have to update file in a repository
Commit the changes against a work item
Is there a better way of introducing version control for VisualFiles. Because to me this feels like not an ideal solution
Thats pretty much the only solution at the moment. The team I am in does something similar but only really for major versions, in minor changes we will feature-switch within the code and leave the old edits inline with dates and initials
The platform provider (LexisNexis) have determined changess to code editor functionality as "likely to implement". This may or may not include version control, that is not yet known, if it does it will be in released v4.1+. There are no other tools available to achieve your aim within the platform. Ask your account manager for access to the ideas portal and you can see when their dev team commit to enhancements such as this.
As source/version control is a long standing issue, any devs using the platform have always had to find workarounds as per your suggestion. The providers are highly unlikely to push any version control functionality with backwards compatability pre v4.
Does anyone know what is the difference between a GitHub release and the actual release that software company announces?
I'm trying to find the different versions of vue.js, on the vue.js official website there are only two versions but on the GitHub repository many releases I was wondered if the two concepts are different?
Release(may be downloadable link) version is just file which is uploaded.
Just they decide to provide only two version(may be latest) on official site.
It is all. If same version, (should be) same file. It is just like top selling tag on a store.
When they release a GitHub version, it is supposed to be open source. The one the company releases may have more code they have not reeased yet or is confidential.
Is there a way to automatically generate a change log from Github issues?
Ideally I want to be able to point at a closed milestone and generate either a plain text list of closed issues with their titles or, even better, a list with markup for links to the issues and the title of the issues themselves.
You can try to use Github-Changelog-Generator. (I'm author of this project)
It generates changelog from tags and merged pull-requests.
This script also have a support of GitHub Issues.
This changelog was generated by this script. CHANGELOG.md
Example:
Changelog
1.2.5 (2015-01-15)
Full Changelog
Implemented enhancements:
Use milestone to specify in which version bug was fixed #22
Fixed bugs:
Error when trying to generate log for repo without tags #32
Merged pull requests:
PrettyPrint class is included using lowercase 'pp' #43 (schwing)
support enterprise github via command line options #42 (glenlovett)
This isn't for Github specifically, but through Git you can run the log through pretty print to generate a changelog style html page.
From https://coderwall.com/p/5cv5lg
git log v2.1.0...v2.1.1 --pretty=format:'<li> view commit • %s</li> ' --reverse | grep "#changelog"
You can use the GitHub API to get a list of issues associated with a given milestone.
For example:
curl https://api.github.com/repos/<user>/<project>/issues\?milestone\=1\&state\=closed
replace <user> and <project> with the username and project and this will return a json list of all closed issues of the milestone with the id 1. You can then, for example, use a script to extract the information you are interested. Here is a python example that prints the list of issues as restructured text:
import json
with open("issues.json") as of:
data = json.load(of)
for issue in data:
t = issue['title']
n = issue['number']
url = issue['html_url']
print "* %s [`Issue %s <%s>`_]" % (t, n, url)
See if the following tool will do for you github-changes.
Disclosure: I'm the author of the tool.
We created an open source project to generate changelog from the list of closed github issues since a given datetime. It's available here: https://github.com/piwik/github-changelog-generator
Not directly through GitHub: that would be a kind of hook that you could put in place, and which would based on naming convention or comment convention that your project might follow.
Even using the issues title isn't always a sure way to generate meaningful change log, unless you review and edit if needed each and every issue title of your project.
In other words, it is very dependent on how you manage your project and not easily generalized to all GitHub repos.
I said as much in a very similar question "Publish a project release (binary/source packages) on Github?".
In addition of a third-party solution (or a GitHub Action like generate-changelog), you might soon Q3 2021, have a native feature from GitHub:
One of the most important parts of the software lifecycle is releasing your code for others to consume.
GitHub Releases will make that even easier by providing compelling and automatic release notes.
When creating a Release, you can click a button to automatically generate release notes.
If you want something more custom, you can a REST API to get the generated release notes and integrate them into your existing releases process.
We also want to ensure that these release notes look amazing when a maintainer shares them and make them easier to discover. We have done a complete redesign of releases to make projects announcements look stunning.
We are surfacing these releases in the feed to increase discovery.
We are also improving the open graph data for releases so they look equally fantastic when shared off of the GitHub platform.
Intended Outcome
Our number one goal is to make it easy for maintainers to create great release notes so more people can discover that amazing work maintainers are doing.
With minimal effort many projects will be able to benefit from detailed release notes.
For maintainers who put more time into their release notes to write editorialized content the intended outcome is that we free up time they are currently spending to maintain custom infrastructure and compile a changelog so they can focus on the most important content for their customers, high quality editorialized content.
Our other goal is to ensure that the release notes look great and are something maintainers and developers are excited to read and share.
How will it work?
The new Releases UI will be able to be enable with feature preview
A new button in the Release creation UI will be able to be pressed to generate release notes from any tag
The generated notes will be able to be configured via a .github/release.yml
A new REST API will allow customers to generate notes at their own convenience to further automate and customize the experience with GitHub actions.
I helped build a jQuery plugin for this recently that uses GitHub issues to communicate app updates directly to the user. The repo can be found here https://github.com/uberVU/github-changelog
Usage is pretty simple:
$(function() {
var $demoChangelog = $('.demo-changelog');
//call the plugin on a dom none
$demoChangelog.changelog({
//give it a repo to monitor
githubRepo: 'uberVU/github-changelog-playground',
});
//manually check for new closed issues
$('.demo-button').on('click', function(e) {
e.stopPropagation();
$demoChangelog.changelog('checkForUpdates');
});
});
My boss announced yesterday a new commit policies for checkins into the repository. This policies are valid for commits into head/trunk and branches.
A commit message must have the following items:
Reason (Bug ID,Project ID, or non functional change)
Name of the reviewer
After the commit we also have to create a change blog entry in our CMS.
I'm not a big fan of this commit policies, because I don't normally need a reviewer when I am doing new or experimental stuff in a non-productive-branch.
Do you have any commit policies do you have to follow?
I think it is a good idea to change the productive-branch only due to a Bug Report, but commits into the development branches should be less restrictive.
Commit early and commit often.
We actually use /trunk as development and tags to branch different releases. Only structural intrusive changes go in /branches.
We actively use tags for production and acceptation releases, so we can go back in time easily. Anything committed in the trunk should only have a message describing what the commit changed or added briefly.
I'm not a big fan of using the message space to link with Bug ID's it still requires a lookup for the ID in which case you could also look it up in the bug tracking software and close it there, which to me is about the same effort.
Not to say i dont like any svn integration:
- We use more goodness of automated nant scripts to make releases which branches them in /tags
- svn props actually store our version numbers :p.
- hook scripts for email notification and message logging (great for copy pasting release notes).
We have a number of policies, which are enforced via an in-house plug-in to Visual Studio. We check that code compiles and that unit tests have be run successfully. At the moment we also check code coverage and issue warnings for code which doesn't have enough tests. We also do various consistency checks and verify that an appropriate task is present in our change management system in order to provide traceability for all changes.
The advantage of tool support is great, as it is not really up to people to respect the policies, but obviously there's a drawback as well as these checks take time to run. However, with many developers it is hard to enforce standards without proper tool support.
A reviewer seems pointless for the reasons you mentioned, because not everything needs to be reviewed by others.
In the past the only commit policy we had (where I used to work) was to include a comment indicating what you changed and why, but that's more common sense than anything else.
A common commit policy is to associate a bug ID to the commit to trunk as a justification. Sometimes, version control and bug tracking systems are configured to enforce this policy.
Our commit policy sounds a bit like yours, only we don't enforce it on task branches (where a task branch is like a developer's sandbox for experimenting).
Our commit comments must include either a change control ID (new feature, enhancement) or an issue ID (bug fix). You must also include a brief explanation as to why you made this change; version control tracks the who, what, when and where.
My commit message include a short describtion what i have implemented or changed in the classes.
The bug number and additional describtions i put in the commentation above the new code. IDs inside the commit messages we put when we merge changes into a tagged branche.
Every night a automatic build checks the different features and products too get sure that the code base is stabil.
But in the end i think you can not have too many describtions for new or changed classes but too many policies you have to do before a commit. The name of the reviewer is something which i would not put into the commit message.
Think about that you sometimes have to undestand your code which you have implemented 2 years ago. And then you are happy about commit messages which are not like "Update after debugging".
We have branches for every released major version of the software that is still actively supported. Checking into any of these branches requires a bug ID - this is enforced by scmbug, which will not only check that the comment is prefixed by the bug ID, but will also look up this bug in the bug database, ensure it is assigned to the committer, and potentially check other criteria (e.g. that the "fix in branch" field is the branch being committed to).
One of the products has more potential to fail in embarrasing ways, and checkins to this require not just a bug ID but a code review as well. However, the criteria for the code reviewing is handled in our bug database - we have custom fields for this and the bug cannot be accepted and closed until it has been reviewed. To me this works from a conceptual level - it's probably better to check code that is believed to work into the repository un-reviewed, then reopen the bug and change it if necessary rather than hold off on committing until you're sure it is ready for release.
Other than that, there's no explicit policy for the trunk (though of course the general tenets of checking in often without breaking the build, including good descriptive commit messages, checking in units of work atomically still apply).