Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Akka HTTP - stable, growing and tons of opportunity #27
We have given this process a lot of thought over the last months, including reaching out personally to many of its significant contributors, as well as considering the long term growth plans of the Akka ecosystem.
In tandem with the upcoming announcement of Akka HTTP becoming a fully stable maintained module, we want to include the following changes.
You, the extended Akka HTTP team
Akka has historically been very strictly owned and driven by the core team, here at Lightbend. With this move, we would like to make an experiment and see if our awesome community is able and interested in taking more ownership and direction-shaping of such an important project as Akka HTTP.
Lightbend and Akka team of course remain heavily invested and interested in Akka HTTP.
We believe it is an important building block for both Akka and reactive applications which like the toolkit (i.e. not-framework) design style that Akka maintains.
Akka HTTP remains supported by Lightbend and we will actively participate in its development. In the short term we promised a few weeks of multiple people working on HTTP/2 as well as final performance improvements. In the long term, we will keep maintaining, reviewing, and working on it, however unlike in the last 2 years we will not exclusively focus only on Akka Streams and HTTP – we have new exciting thing we want to bring to you which you’ll learn about very soon (one of them being the Remoting rewrite, Artery).
Action: This is simply to state, there is a lot of work to be done, and plenty of awesome developers out there that we know are able to pull it off, so we’d like to recognise those efforts by awarding a place for the Akka HTTP team in the github organisation.
Highly Open Participation
As a general rule, we’ll even more strongly than ever before, focus on a highly open and transparent way to participate and shape the future of Akka HTTP.
We would like to nominate a number of people–whom we highly value for their past and current participation in both the Spray as well as Akka HTTP project over the last year–to form the seed of the Akka HTTP team on github. This team is specifically not-only-lightbend employees, and it’s aim is to allow various people with a strong commitment in Akka HTTP to help shape its future and be recognised for it in more than just release notes.
The people whom we’d like to invite to form the initial Akka HTTP team are:
The team will have merge rights in the project, so will be able to help the community get more pull requests reviewed and merged more quickly.
We initially don’t see the need to split the gitter channel or mailing list, those shall remain gitter.im/akka/dev for developing akka and gitter.im/akka/akka and akka-user for questions about using Akka.
Question: We are also thinking about scheduling a bi-weekly hangout, that would be open to anyone to attend in which we’d talk about the direction and important things to work on next. Let us know if this sounds useful and we’ll figure something out.
It would be possibly a good opportunity to improve the collaboration in the Akka HTTP team by growing our bonds through more than just typed text and tickets.
A new Versioning scheme for Akka HTTP
Binary compatibility is very important to us. We’ve shown one of the best track records in the Scala ecosystem on maintaining such compatibility–including efforts that we spent between 2.3.x and 2.4.x that made these binary compatible, which would have–under the previous versioning scheme–been major releases.
Please note that Akka, since the release of 2.4.0 maintains a MAJOR.MINOR.PATCH versioning, as opposed to the previously used EPOCH.MAJOR.MINOR which used to be Scala versioning scheme inspired.
We can not use the 1.0 version to demarcate this new start as it would be very confusing since that number was already used back in July 2015 while we were working on Akka Streams & HTTP under a separate version scheme than Akka "core", which was at 2.3.x and later on continued to become 2.4.x.
Our goal with the HTTP versioning scheme is to signify that while Akka HTTP may need to bump its major version number, e.g. from 10 to 11, it would be still compatible with Akka 2.x–the stable core which will only break compatibility when a huge change is needed.
Action: After careful consideration of all of the above constraints, we propose that the new versioning scheme be different enough not be confused with Akka "core" versions. Specifically, we think using a version number much higher than 2 or 3 (which would be confusable with Akka versions) is the way to go, and suggest to start at 10.0, simultaneously announcing Akka HTTP to be stable (removing the experimental flag).
To decide: Given troublesome situation of the Directives trait being extended by user code, binary compatibility is impossible to maintain when a new directive is added into it. This will change with Scala 2.12, however with 2.11 it still is the case. We propose to keep source compatibility in minor releases, e.g. a new directive can be added but to a new trait that one mixes-in explicitly, and in a major release we can merge those new traits to the existing Directives structure. A major release may then still happen sooner than an Akka 3.0 (which is very far out), and the project can keep a healthy speed - to be determined by the team.
Akka always was and still is well known for it’s excellent documentation and we intend for it to not only stay this way, but become even better!
Our largest challenge currently with this came with the growth of documentation pages, especially with the addition of Akka HTTP and it’s more than 300 directives (all directives and pages available in both Scala and Java), it is becoming more difficult to read / browse the entire docs together.
Therefore, we would like to split up documentation in different module sub-directories. For example, specifically this means that we’ll move all of Akka HTTP docs to a root-level "http" directory on doc.akka.io.
Additionally we want to move the documentation to Lightbend Paradox a documentation engine. It is much simpler to use than Sphinx and ReStructured Text which Akka is using currently because it is plain Markdown. It will shortly gain fine-tuned Scala documentation features and and can even include executable Akka.js snippets using ScalaFiddle. You can get a glimpse of how documentation with embedded runnable Akka Streams snippets might look like on this example page prepared by Andrea Peruffo (from the Akka.js team).
As you know, we included Algolia powered search in our docs so it’s now much easier to find the right thing in the docs. Often however, you are searching for things in context–i.e. "I’m looking to do X in Akka HTTP" or specifically looking how to do something with Reactive Kafka. Often similar search queries, and confining the search to a given module will yield in a better search experience.
Action: Docs will be hosted under doc.akka.io/ as is currently, however will be moved to their own top-level directory, e.g. doc.akka.io/http/10.0/. We will attempt (and need help doing it, there’s a ton of documentation) to move from Sphinx to Paradox, which should be much simpler to contribute docs with as it’s plain markdown.
Exciting and upcoming: HTTP/2
As briefly mentioned in release notes over the last months: yes, we will work on an HTTP/2 proof-of-concept for Akka HTTP. It is important to realise that unlike for example Play which relies on Netty for implementing the HTTP layer and can simply upgrade netty to get this capability, Akka HTTP is an entire web server, thus the responsibility of implementing all low level bits of the HTTP/2 protocol fall into the hands of akka-http-core.
Action: We will spend a number of weeks developing an HTTP/2 PoC, however are not sure how much features we’ll be able to implement during that time. When we start the HTTP/2 sprint, we’ll invite you, the interested parties in this feature to review, help, and contribute to get this the best possible support. In other words, with the project becoming more and more community led, we would like to encourage a "vote with code" approach–if a feature is important, it should be able to attract contributions to see it shipped.
We believe this move is both important and exciting. It will allow to grow the community not only sheer size but also strength and go where no man has gone before. Feel free to comment in this meta thread if you have any thoughts on the topic.
More technical details which we need to decide before calling the module stable will be debated on the github.com/akka/akka-http repository. For example stating and explicit source compatibility requirement or perhaps deprecating the "trait-style" way of using directives to allow us to keep binary compatibility in much more situations.
Again, we’d like to stress that we want to hear and see both feedback and code from you all.
Let’s get hakking!
referenced this issue
Aug 22, 2016
Looking forward to the move!
My answer to two of the questions.
Yes. It's currently 219 tickets. I don't know what is the best way to do that.
That is a must. Not necessarily the exact same commit identifiers, but the authorship must be preserved.
We also started a ticket that was supposed to carry the discussion more
Maybe move further replies there?
On Thu, Aug 25, 2016 at 3:41 PM, drewhk email@example.com wrote:
Yes, we'll move them. All akka-http tickets should be moved into this repo.
I'll figure out if asking github could make moving the tickets somewhat smarter (perhaps they can redirect from old ones etc)
In my mind the trickiest things nowadays are:
Most other things are new features that we can start adding in the new cycle.
Odd yes, but less dangerous to confuse.
Let's discuss versioning in akka/akka-http#3
akka-http, akka-http-testkit and all the json and xml things for sure.
akka-http-core is tricky, let's discuss in akka/akka-http#9
My current thinking is that moving is healthier, because if someone looks for akka http or files a bug, they'd do so in the akka-http repo. I don't want to explain to people who just found a bug that they're reporting in the wrong place.
Yes, that's part of the plan – @hseeberger already pinged about akka-sse, and I think we could be by far more aggressive in including things and offering their maintainers committer rights in akka/akka-http.
This is an open invitation, if you feel your module makes sense to be included please step up and let us know.
E.g. akka-http session, more json support traits, caching etc are great candidates here.
Yes, as Patrik said this is a must.
Let's discuss that in the versioning scheme topic as it relates to how we bump versions.
Do you have some specific ones in mind? Akka HTTP (the DSLs) were breaking compatibility.
I like that idea a lot!
Let's continue on it here: akka/akka-http#10
E.g. things like