V2 Roadmap

[geromegrignon]

V2 Roadmap

This issue is dedicated to the Roadmap of the upcoming new version of the specs.

Introduction

Get ready for a new version of the specs!
Since the release of the RealWorld project in 2017, the standards of a modern and 'real world' project have changed. These changes have been partially identified through open issues we need to address right now.

But some of these issues will introduce breaking changes. While it might be easy to deal with such changes for a lot of projects, the nature of the current one is different. By updating the specs, implementations have to be updated accordingly.

As a lot of the listed implementations are currently left unmaintained and as we don't have control over them, we can't rely on them to be updated on their own. These implementations are still viable and valuable.

So by updating the specs, we decided to open the registration of a brand new generation of implementations. We'll create a new list of implementations based on the new specs to showcase them on a dedicated page on CodebaseShow.

This decision is also a great opportunity for this project to provide a more realistic set of specs for more real RealWorld implementations.
Among other things, we want to make front implementations responsive and accessible and to help you to build a community with your implementation.

Here are the reasons for this move and the upcoming state for the current implementations.

Breaking changes

We can't move forward without addressing issues that will introduce breaking changes.

Open source standards

We already made some changes to the project to be closer to open source standards.

We plan to go further by enhancing the current starter kit by including those open source standards.

Github isn't just a tool to host projects so we want to get the most of it through features like Github Actions or Github Apps.

Where can I find the complete list of changes?

Besides the current list of opened issues, we'll open RFC (Request For Comments) issues to engage with the community: we want to allow everyone to contribute to those changes.

This current section will be updated accordingly with links to those RFCs.

Current implementations

We really value the implementations already created.

Several months before releasing the new specs, we'll invite maintainers of the current implementations to make a choice : to move their implementation to the new specs (we'll remove their implementation from the v1 listing) to create a new repository to host the v2 version of their old implementation

Those implementations will have the priority upon providing updated versions of the current implementations. However, if our request remains unanswered, we'll invite the community to submit new implementations

CodebaseShow changes

On CodebaseShow each version of the specs will have a dedicated listing.

Roadmap

[ACTIVE STEP] Choice of new official implementations (July-August 2021)

To showcase/experiment changes, we need a set of frontend/backend implementations. A RFC is currently open so everyone can give his/her opinion about the best stack to use

Creation of repositories for new official implementations

Based on the previous step, 1 frontend and 1 backend repositories will be created in the Github organization

[ACTIVE STEP] Creation of implementations

An implementation based on the current specs will be added to these repositories.

Adress issues

The maintenance team and any contributor can address current issues by opening Pull Requests in these 2 repositories. a V2 branch will be created in the realworld repository to make changes in the specs for each Pull Request.

FRONTEEND

UI

• display avatar placeholder #689
• clearer pagination #684
• stylesheet distribution #662
• tags clickable #649
• settings refactor #630
• tags addition #628

ROUTING

• distinct navigation routes #691
• route redirection #690
• fallback route #650

SECURITY

• web security #525

BACKEND

• ambiguous API routes #695
• update user bug #681
• load testing #666
• API responses #661
• idempotency #659
• docs /swagger /postman collection inconsistency #626 #380
• API HTTP verb #582
• username format #484 #116
• API endpoint #442
• expected parameter #410

GLOBAL

• username option for Auth #683
• forgot password feature #419
• search feature #110

Adress Concerns

Besides dealing with current open issues, the goal is to review the existing specs and make them easier to use :

Here are some topics :

• make the HTML more accessible by using aria attributes and semantic HTML tags
• provide specs for web security
• find a way to easily test the web security implementation (like using https://securityheaders.com/)
• provide an interface to explore the swagger api
• to test the API, you have to clone the real-world project: find a way (like a library) to avoid such a need
• to remove the specs being in the starter repository (as a duplicate version and break the single source of truth rule)
• to test the web performance (considering using lighthouse CI)
• add loading and error handling

It's not a closed list as we'll consider community contributions too. We aren't making those changes for ourselves but the community.

[geromegrignon]

@aisensiy : I'm working on a new section on this issue to give more insights about the changes on the specs.

[nettybun]

Are you asking the community what they consider "real world" for web application development in 2021 compared to the current 2017 spec? Between #693 and #694 I don't see any actual proposals just introductory text...

I was expecting to see a changelog such as:

• Must provide OAuth/SAML authentication; use of JWTs is optional
• Must be live and reactive to changes on the server via websocket or server-sent events
• Page load size must be < X.XX kb
• ...

Are these the kind of changes you're hoping to bring? Or is "V2" only about adopting GitHub Actions/CI.

Thanks!

[geromegrignon]

Hello @heyheyhello, thanks for your questions.

I updated the initial comment to give more insights about the Roadmap. I can't deliver a full changelog as the goal isn't to make the changes I want but the changes the project needs. To achieve this, I'm currently compiling the requests made on all current implementations to give more insights about the changes we can do (and the ones we won't).

About the kind of changes we want to bring, it's indeed more about the specs than the Github platform (Github being a tool to help us to review the implementations proposals).

[geromegrignon]

@aisensiy i updated the original comment about changes.

[aisensiy]

Hmm...It seems not too much upgrade in the backend part. Just kind of fixes...

[geromegrignon]

Hmm...It seems not too much upgrade in the backend part. Just kind of fixes...

Most of the propositions are community ones. I encourage you to open feature requests for upgrades you would like to see added to the v2.

[geromegrignon]

[UPDATE]

• The #694 RFC will close on September 6.
• I should be promoted to be able to create repositories on September 6 to create repositories for new official implementations
• a new official backend implementation has been created and deployed (https://realworld-temp-api.herokuapp.com/api)

[geromegrignon]

Hey @heyheyhello, I started a dedicated and more explicit changelog : https://github.com/gothinkster/realworld/issues/808

[adamerose]

Suggestion - Add light / dark theme toggle

I think using CSS variables for colors in #662 would make this easy.

[jaguililla]

Hello, I'm testing a backend implementation against this Postman collection: https://raw.githubusercontent.com/gothinkster/realworld/main/api/Conduit.postman_collection.json

Will the changes on the API scheduled for the V2 be released on that same collection? Or do I have to change the URL pointing to the acceptance tests?

Thanks!

[geromegrignon]

Discontinued task: we have too many existing implementations for a v2 to be viable, especially knowing most of them are not maintained and maintainers do not answer to update requests.

The project will keep its current shape.