Release v0.6.0

[leandro-lucarella-sociomantic]

We should make the next release v0.6.0 instead of v0.5.x.

I strongly suggest using neptune-release to make the release. This will take care of making sure the tag is done correctly, create a GitHub release, close the milestone, etc.

I think we should also provide a decent changelo/release notes for this. Neptune can help with this too, you can just create a file in relnotes/ and the release notes will be aggregated automatically by neptune-release.

We should also make sure PR adding new features or breaking changes provide release notes.

As long as we don't ship a first v1.0.0, I suggest we only ship bug fixes in patch releases (v0.x.) and only add new features and/or breaking changes when incrementing the minor version (v0..0).

[wilzbach]

Excellent idea to have everything standardized. Maybe it's a good idea to add a description of the release process in the README, s.t. it's hard to forget?

I strongly suggest using neptune-release to make the release.

Looks good. What's the plan? Is someone supposed to be responsible for putting out new releases or is this just specified and anyone who merges a new feature is supposed to tag a new minor version?

can just create a file in relnotes/ and the release notes will be aggregated automatically by neptune-release.

Sounds familiar to D's changelog directories :+1:, but might be an overkill for now - especially if there's a new minor release for every new feature.

[leandro-lucarella-sociomantic]

Excellent idea to have everything standardized. Maybe it's a good idea to add a description of the release process in the README, s.t. it's hard to forget?

Yeah, we usually provide links to the neptune repo. The project is some kind of guideline/recommendation on how to implement SemVer, and it provides documents describing those guidelines and some tools to help you with that if you follow the recommendations there.

It's more focused on libraries for now, but we are already using it to release tools too (for example the git-hub) and it was quite a success too. We even have a document on how to use it for applications, although is a bit more vague than the doc for libraries.

We know it might be a bit incomplete for now, specially regarding the release tool (which is still in the early stages, but already very useful). Since we are using it already, is hard to know exactly how badly documented things are, so having an external eye on it to point us out what's missing would be great (and PRs would be AMAZING :D).

I strongly suggest using neptune-release to make the release.

Looks good. What's the plan? Is someone supposed to be responsible for putting out new releases or is this just specified and anyone who merges a new feature is supposed to tag a new minor version?

We make releases "manually" by running the tool when they are ready. Actually we try to make releases on a regular schedule, but I think this is not documented in neptune (at least for now).

I think depending on the project's pace, having minor release cycles of between a month and 6 months seems reasonable. If the project has almost no activity, I think is fine to make a release more or less every time a new feature is out..

Sounds familiar to D's changelog directories 👍, but might be an overkill for now - especially if there's a new minor release for every new feature.

Why is it overkill? And what do you find overkill exactly? To write the release note at all or to write one per file?

I think release notes are super important, and usually when you write a new feature, writing a release note only takes a few minutes, so I don't see why shouldn't we do it.

[leandro-lucarella-sociomantic]

Also, the good thing (?) about neptune, is even if you don't have the release tool or you don't want to install it, making a release is not more work than it should be, we wrote the tool because we were tired of doing the same over and over again and sometimes we forgot some step(s). But basically what it does it:

• Find out what the new tag should be (based on the current branch, if it's v0.5.x then it looks for the latest v0.5.N tag and increments N, if it's v0.x.x, it will look for the latest v0.N.0 tag and increment N, etc.)
• Compile release notes (basically echo "Migration instructions"; cat relnotes/*.migration.md; echo "New features"; cat relnotes/*.feature.md> /tmp/release-notes.md)
• Create tag with release notes as message
• Create GitHub release with release notes as body
• Close milestone to be released (if found)
• Create new branch
• Clear release notes and commit to new branch
• Maybe something else?

But even some of those can be done on demand in the future.

[wilzbach]

Yeah, we usually provide links to the neptune repo.

is hard to know exactly how badly documented things are, so having an external eye on it to point us out what's missing would be grea

Hehe - I don't have much time for a detailed look into atm, but here's how I reacted:

• so what's this doing?
• okay, so it's protocol for SemVer with a lot of documents (browsing the documents)
• okay, that roughly sounds like standard SemVer procedues
• wait, there are two binaries now - what do they do?
• ...
• jump to src/release/main.d
• okay so it does a lot of useful stuff, but how am going to know what happens without reading the source and without documentation or simulation flag
• meh I'm not going to use this today (aka bounce)

Actually we try to make releases on a regular schedule,

That would be a bit difficult here, because manpower is sparse ... except, of course, Sociomantic pushes for it and handles the regular releases ;-)

Why is it overkill? And what do you find overkill exactly? To write the release note at all or to write one per file?

Because of this:

If the project has almost no activity, I think is fine to make a release more or less every time a new feature is out..

Anyhow I was just saying that the tooling around could easily be more work than the activity of this repo.

Also, the good thing (?) about neptune, is even if you don't have the release tool or you don't want to install it, making a release is not more work than it should be, we wrote the tool because we were tired of doing the same over and over again and sometimes we forgot some step(s). But basically what it does it:

Well, until now binary releases weren't provided, so doing a release was as simple as adding a new tag ...

Anyhow here's my proposal to keep it simple for now:

• summarize your ideas about new releases in the README (after they have been approved by @Hackerpilot)
• maybe start a thread at https://github.com/dlang-community/discussions/issues to use the same policy for all repos
• start following the tagging guidelines

Optional: If Sociomantic wants to take care of the release process, that's cool and they obviously they can use neptun for it ;-) But I think specifying that new features should get a new minor version should be enough for now and if there's really more activity, more process can be setup.

[leandro-lucarella-sociomantic]

but here's how I reacted

Yeah, sounds fair. I guess at a bare minimum we should include some sort of online man page with the basic description and options for each tool.

That would be a bit difficult here, because manpower is sparse ... except, of course, Sociomantic pushes for it and handles the regular releases ;-)

I think is very likely that we can commit to that. We were going to do so anyway in our fork if the repo wasn't moved here.

Because of this:

If the project has almost no activity, I think is fine to make a release more or less every time a new feature is out..

But I still don't see the problem here. Every new feature or breaking should come with a small note of what changed. The amount of work needed to write the release notes is proportional to the amount of PRs with breaking changes/new features, not to the number of releases we make; and the work of writing the notes is evenly distributed among the PR writers, so it's not even a lot of work for only one person.

Anyhow I was just saying that the tooling around could easily be more work than the activity of this repo.

Oh, so the tooling is your concern, not writing the notes? Would that change if we say we'll take care of the releases? Ah, I should read everything before writing the reply

Optional: If Sociomantic wants to take care of the release process, that's cool and they obviously they can use neptun for it ;-)

Yes, specially if you say the activity is low in this project I don't see why we couldn't take care of releases. If we use neptune release is literally just run one program to make a release.

We will need to be sort of the gate keepers of PRs too to do this though, because I wouldn't accept PRs that don't provide a decent release note when required. If someone else start accepting PRs blindly, then the release process will become much more messy for us.

[wilzbach]

I think is very likely that we can commit to that. We were going to do so anyway in our fork if the repo wasn't moved here.

:+1: - that's one of the reason why I started dlang-community. Shared profit and efficiency by more collaboration :)

Oh, so the tooling is your concern, not writing the notes? Would that change if we say we'll take care of the releases?

Yes and yes. I know how much time Martin Nowak is putting into the entire release process :/ So I was just afraid of introducing lots and lots of guidelines and tooling without anyone being around interesting in enforcing or using them.

We will need to be sort of the gate keepers of PRs too to do this though, because I wouldn't accept PRs that don't provide a decent release note when required. If someone else start accepting PRs blindly, then the release process will become much more messy for us.

I don't think this will be a problem. Our general guidelines already forbid self-pulls (direct push + push with failing CIs is disabled) and imho it's more than reasonable to expect other reviewers to look out for this though not all sheep are equal and it might require an occasional reminder in the beginning (see e.g. https://github.com/dlang/dmd/pull/7484#issuecomment-361316930).

[leandro-lucarella-sociomantic]

So I was just afraid of introducing lots and lots of guidelines and tooling without anyone being around interesting in enforcing or using them.

I would be happy if we maintain this repo in a "neptune-style" as an experiment at first (instead of rolling it out to all dlang-community, which would be a big task and also the tools are still in early stages of development, so I don't think is ready for mass adoption). But using neptune in a repo that is more widespread and watched by more people could also help us to see what's missing in neptune (I guess people will complain when they don't understand why or how we do something), and help maturing it, so maybe in the future it can be adopted by more dlang-community projects.

I don't think this will be a problem. Our general guidelines already forbid self-pulls (direct push + push with failing CIs is disabled) and imho it's more than reasonable to expect other reviewers to look out for this though not all sheep are equal and it might require an occasional reminder in the beginning (see e.g. dlang/dmd#7484 (comment)).

👍

Then I think we can definitely give this a try.

Let me know if you agree to start using netpune as a pilot program here and take over the release process. First step will be create the new branches and release 0.6.0 with what's in the current master.

[wilzbach]

I would be happy if we maintain this repo in a "neptune-style" as an experiment at first (instead of rolling it out to all dlang-community, which would be a big task

Sure. Sounds fair. I was more referring to the point of doing using minor versions instead of -alpha, which is more a matter of documentation.

Let me know if you agree to start using netpune as a pilot program here and take over the release process. First step will be create the new branches and release 0.6.0 with what's in the current master.

Yes, I'm not only okay, but very happy about this experiment. However, you should wait for the approval of @Hackerpilot - he is/was the author of dfmt - and even though we now have shared the maintenance overhead among multiple people, I still think we should include him into bigger decisions.

[Hackerpilot]

The release process isn't very interesting to me, so I'm fine with somebody taking over that part of dfmt.

[UplinkCoder]

@leandro-lucarella-sociomantic @wilzbach Alright, let's clean this situation up.

It's not like downstream projects are dependent on dfmt source, so as long as the commandline interface is not broken we should be good.

[leandro-lucarella-sociomantic]

Sure. Sounds fair. I was more referring to the point of doing using minor versions instead of -alpha, which is more a matter of documentation.

I don't get this, minors and alpha releases are completely different (almost the opposite I would say, one is the most stable type of release and the other the most unstable type of release :).

In any case, we'll be happy to take over the releases of dfmt! Let's see how it goes :)

[jacob-carlborg]

I don't think it needs to be so complicated:

• Setup a job in Travis CI that runs on tags
• The job builds the binary and uploads it to a GitHub draft release. Travis CI has built-in support for this
• Write some release notes on the GitHub release
• When the release is ready, publish the release (i.e. it's not a draft release anymore)

Here's one of my project that builds and creates a GitHub release automatically on push. Travis CI configuration [1], simple shell script that builds the release and creates a tar archive [2]. Make sure the Dub configuration builds for the appropriate platforms [3]. Building a completely statically linked binary on Linux makes sure it works on all distributions.

With this workflow every push of a Git tag will create a release.

[1] https://github.com/jacob-carlborg/remarkify/blob/master/.travis.yml#L10-L29 [2] https://github.com/jacob-carlborg/remarkify/blob/master/build_release.sh [3] https://github.com/jacob-carlborg/remarkify/blob/master/dub.sdl#L7-L8

[leandro-lucarella-sociomantic]

@jacob-carlborg thanks for the suggestion. If we are going to handle the releases, using the neptune is the easiest option for us though, and it makes everything more orderly (it covers more than just creating a tag and a GitHub release). Nothing prevents the project adopting another scheme if someone needs to take over the release process.

Back to implementing this. To fully implement neptune it's strongly recommended to remove master and always use explicit branches (v0.x.x or v0.5.x for example). We are going to move forward with this if we don't hear complains in the following couple of days.

[jacob-carlborg]

Back to implementing this. To fully implement neptune it's strongly recommended to remove master and always use explicit branches (v0.x.x or v0.5.x for example)

That's very unorthodox, to remove the master branch. Why would you do that and where would the main development happen?

[leandro-lucarella-sociomantic]

In the lowest maintained minor branch. This is to avoid confusion about what master really means in terms of maintained branches, and also because master is usually the bleeding edge branch, and we don't want new features to go to the latest bleeding edge branch but to the oldest minor branch. The idea behind neptune is to force users to move to the latest bleeding edge versions as little as possible.

You can check neptune docs for details: https://github.com/sociomantic-tsunami/neptune/blob/master/doc/library-maintainer.rst#removing-the-master-branch

[leandro-lucarella-sociomantic]

I know for someone not used to this scheme it might be hard to grasp at first, but believe me, this scheme is tested and working very well for a lot of internal and open source project (you can check out https://github.com/sociomantic-tsunami/ocean, https://github.com/sociomantic-tsunami/swarm or https://github.com/sociomantic-tsunami/git-hub for example).

Since we will handle the release process for this, you don't have to care much about it, just give it a chance and see how it works. As an user you will not even note that anything changed, as a developer if you send PRs you don't have to care much either, worst that could happen is doing the PR against the wrong branch and we'll let you now, then you just need to rebase the PR to the correct branch and that's it.

[jacob-carlborg]

we don't want new features to go to the latest bleeding edge branch but to the oldest minor branch

What!! Isn't, by definition, the branch that receives new features the bleeding edge branch? If not, what makes the bleeding edge branch bleeding edge?

[ghost]

i dont see any problem, if you think that it's 0.6.0.

[leandro-lucarella-sociomantic]

What!! Isn't, by definition, the branch that receives new features the bleeding edge branch? If not, what makes the bleeding edge branch bleeding edge?

Breaking changes and refactoring. New features usually poses no risk to update. It would be interesting if you could read the docs in neptune. :)

[leandro-lucarella-sociomantic]

OK, @jacob-carlborg , you seem to be the last person not convinced with the move. Can we get the benefit of doubt and move forward. Again, if this turns out to be a failure, we can change the release process in the future again, no big risks here :)

[jacob-carlborg]

Sure, go ahead.

[jacob-carlborg]

@leandro-lucarella-sociomantic if you're going to release binaries, I recommend static linking using LDC on Linux and the BSD platforms. On macOS make sure to specify a minimum deployment target of 10.7 or any newer version if that's required.

[leandro-lucarella-sociomantic]

For now, and the foreseeable future, we only plan to release binaries in the form of Ubuntu/Debian packages via a Bintray repository. We might consider other options in the future (in particular if there is demand), although I don't see ourselves providing the automation to build for BSD and macOS, as we don't use those, I guess someone else would have to step in for that.

[jacob-carlborg]

For now, and the foreseeable future, we only plan to release binaries in the form of Ubuntu/Debian packages via a Bintray repository.

That's a disappointment 😞.

[leandro-lucarella-sociomantic]

That's a disappointment.

Sorry about that, but it's not a regression in that sense, previous releases didn't provide any form of binaries, so providing Ubuntu/Debian packages for releases is actually a step up. Also, since we don't use those systems I think it would be even a bit irresponsibly to do the releases / build ourselves, as we wouldn't be eating our own dog food (as we are with the apt repo :).

[leandro-lucarella-sociomantic]

OK, we made the first release using neptune. As we had some internal misunderstandings and an earlier attempt of release was failed inadvertently, we re-created the v0.6.0 tag (and force-pushed to the new v0.6.x and v0.x.x branches).

Sorry if these very unusual steps and maybe any other spurious GitHub notifications caused any problems, they were just problems on setting up the initial release process and we hope future release to go way more smoothly!

[leandro-lucarella-sociomantic]

https://bintray.com/dlang-community/apt/dfmt/v0.6.0

[jacob-carlborg]

Sorry about that, but it's not a regression in that sense, previous releases didn't provide any form of binaries, so providing Ubuntu/Debian packages for releases is actually a step up

What you have describe and what I've tried to read in the documentation provided by you, there are several downsides.

• Having the default branch that changes from time to time will cause all pull requests to break, it will also force any developers to update their Git repositories locally. This will also make it more difficult to attract more contributors

• Having an unusual release process will make it more difficult for new contributors or to add support for releasing to other platforms

• I also just noticed now that testing was disabled on macOS. How is this not a regression?

• Making up new meanings of existing words. I would consider "bleeding edge" to include the latest features. But I don't consider refactoring "bleeding edge". If I move an extern(C) function from one module to another module I would consider that a refactoring. I also think that the compiler could potentially generate the exact same binary as before the refactoring. I don't see how this would be "bleeding edge"

[leandro-lucarella-sociomantic]

Having the default branch that changes from time to time will cause all pull requests to break, it will also force any developers to update their Git repositories locally. This will also make it more difficult to attract more contributors

This is a two-sided issue, what you see as downsides, I think can be considered as upsides. Having stale PRs that point to a branch that is super old and there were many breaking changes since the PR was done doesn't make a whole lot of sense to me. If better to be signalled more explicitly that the PRs is outdated. If the PR is close enough, then changing the base branch should be trivial anyway. Also bear in mind changes in the default branch are not that often, it only happens for major releases.

How this might impact contributors, I'm not sure, maybe you'll just attract a different set of contributors depending on which scheme you like more. :)

But for the most common contributions, this should really change much. If you are submitting a bug fix, then extra care is always needed. Either you apply bug fixes to some stable branch (in which case you don't care about master, and this is the case for neptune, so nothing changes here), or you apply it in master and then you need to backport the change to the stable branch (in this case you'll be confused about not making the PR against master, but you'll need the extra step of backporting the fix). I think having a stable branch for bug fixes is pretty common so it shouldn't surprise many developers. If you are proposing a new feature, then things change a bit because there is no master, but if you are a incidental contributor, you clone the repository and bam! You are in the right branch to do your PR without any extra work, just like with master, only that it's not called master. If you make breaking changes is the only case where you actually need to check out another branch, but again, if your project is semver based you need to have a separate branch for that anyway.

So, yes, there is change, there is no master branch and that might scare people, but in practice I don't think there are any major operative problems, it's just scary.

Having an unusual release process will make it more difficult for new contributors or to add support for releasing to other platforms

I don't see why a different branch name could affect adding more platforms. I can see there might add some friction for some people to step-in, maybe. Same as with the default branch (you are the living example that it makes some people uncomfortable, but is that enough to discard a scheme that works and it's useful? Remember when people got uncomfortable about Subversion? And then Git?).

I also just noticed now that testing was disabled on macOS. How is this not a regression?

AFAIK this is not related to neptune, it was just because the service was unreliable and we just got reds in PRs because of time-outs in the CI.

Making up new meanings of existing words. I would consider "bleeding edge" to include the latest features.

Where did you find that definition? I don't see it in the neptune docs. I know I said that, but I was just giving a very summarized version of the docs. "bleeding edge" for me always meant it's very likely to break, and Wikipedia seems to confirm my feeling: "Bleeding edge technology is a category of technologies so new that they could have a high risk of being unreliable and lead adopters to incur greater expense in order to make use of them." (https://en.wikipedia.org/wiki/Bleeding_edge_technology). Neptune fully adheres to this meaning:

• {Minor releases} may contain new features, deprecations, and minor internal refactorings that don't affect the API.
• {Major releases} may contain breaking changes to the API (including bug-fixes or new features which require API changes), removal of deprecations, or larger refactorings

---

As a corollary, I want to clarify something here, because I want to give this a closure. Sadly, since we only have very limited resources to spend on this, there are 2 alternatives for us:

• We take care of upstream releases on the limited fashion we can offer, taking fully care of the use cases we have and promising to do our best to support people that want to take over the use cases we don't have (which means using neptune, as this tools takes a LOT of work off of our backs and helps us provide solid, stable and predictable releases).

• We do exactly the same we mention in the previous point but on a fork that we'll use internally.

Coming up with another release scheme and set of tools to make solid releases extremely easily or support platforms that we don't use ourselves is sadly not an option for us.

So I guess the issue here for the community is to decide what's more useful, if we do the releases with the tools we have for upstream or in our fork.

Sorry if the scenario is harsh, I know it might sound as "our way or the highway", but I'm just being realistic, we have very limited resources and the only way we can commit to take care of the releases is if we do it this way. If you decide it's better to keep doing things as they were before, we understand, fully and absolutely, we just thought that the status quo is improved if we take care only of a subset of what the project needs.

[leandro-lucarella-sociomantic]

I also just noticed now that testing was disabled on macOS. How is this not a regression?

Disable osx, # disabled until travis has more mac resources

Nothing to do with neptune.