Clear out master, move 0.10.x dev to the stable branch

[bf4]

Status:

• ❗️ All existing PRs against master will need to be closed and re-opened against 0-10-stable, if so desired
• ❗️ Master, for the moment, won't have any released version of AMS on it.

Changes to 0.10.x maintenance:

• The 0.10.x version has become a huge maintenance version. We had hoped to get it in shape for a 1.0 release, but it is clear that isn't going to happen. Almost none of the maintainers from 0.8, 0.9, or earlier 0.10 are still working on AMS. We'll continue to maintain 0.10.x on the 0-10-stable branch, but maintainers won't otherwise be actively developing on it
  • We may choose to make a 0.11.x ( 0-11-stable) release based on 0-10-stable that just removes the deprecations.

Changes in this PR:

• The code and docs have been removed from master to signify that development against master has been suspended. When choosing ways that people might be surprised by the current state of 0.10.x development, we thought it would be simpler to make master simply incompatible with 0.10.x PRs than to ensure none are merged.

What's happening to AMS:

• There's been a lot of churn around AMS since it began back in Rails 3.2 and a lot of new libraries are around and the JSON:API spec has reached 1.0.
• If there is to be a 1.0 release of AMS, it will need to address the general needs of serialization in much the way ActiveJob can be used with different workers.
• The next major release is in development. I am building and extracting it from an app I'm working on and thereby dogfooding it myself to ensure it to see if it makes sense. I'm starting simple and avoiding, at least at the outset, all the complications in AMS version, especially all the implicit behavior from guessing the serializer, to the association's serializer, to the serialization type, etc.
• The basic idea is that models to serializers are a one to many relationship. Everything will need to be explicit. If you want to serialize a User with a UserSerializer, you'll need to call it directly. The serializer will essentially be for defining a basic JSON:API resource object: id, type, attributes, and relationships. The serializer will have an as_json method and can be told which fields (attributes/relationships) to serialize to JSON and will likely not know serialize any more than the relations id and type. Serializing anything more about the relations would require code that called a serializer. (This is still somewhat in discussion).
• If this works out, the idea is to get something into Rails that existing libraries can use.

Steps:

1. review this PR, clearing out master, moving 0-10 dev to 0-10-stable
2. merge it
3. make a PR from dev to master and work on it

• add rails rubocop https://github.com/rails/rails/search?utf8=%E2%9C%93&q=rubocop&type=
• I'm currently using the dev branch (in which the gem is named ams in our new api I'm building, so am dogfooding it)

[mention-bot]

@bf4, thanks for your PR! By analyzing the history of the files in this pull request, we identified @remear, @dubadub and @domitian to be potential reviewers.

[bf4]

Noting some of the changes

[bf4]

gets its own changelog

[bf4]

gets its own changelog

[bf4]

gets its own changelog

[bf4]

just references other changelogs

[bf4]

these links weren't up to date

[bf4]

0-10 is no longer master

[bf4]

this won't work on master.. maybe should link to 0-10? or no link?

[bf4]

0-10 is no longer master

[bf4]

0-10 is no longer master

[bf4]

just picked something so tests can run

[mauriciopasquier]

What about Adapters? I'm in the process of migrating from 0.8 to 0.10, and was planing to write a few Adapters to fit my needs. Right now (0.8) I'm basically using model Serializers to describe a "neutral" hash of the model and I use specific serializers to convert that neutral representation to GeoJSON, CSV and JSON:API.

Will the Serializer/Adapter model be compatible with the new work beign done? From what I read here, my approach of having a specific serializer for a needed format (i.e. GeoJSON) will be prefered.

[bf4]

@mauriciopasquier At this time, it appears that adapters may be a special case for serializers. I haven't fully fleshed this out, yet, but basically you'd have your UserSerializer and your DocumentSerializer and combine the two to serialize the user into a JSONAPI response document. I'm starting from a place with no magic so that the fundamentals of how the combine the parts are less hard to work with. I imagine something like DocumentSeriarlizer.new(UserSerializer.new(user)).as_json.

[mauriciopasquier]

@bf4 So I guess I'll stay with that approach. What I'm doing exactly in 0.8 is:

# In a controller
format.geojson do
  render json: @users, serializer: GeojsonCollectionSerializer
end

# In the collection serializer `as_json` method
object.map do |user|
  GeojsonUserSerializer.new(user).as_json
end

Of course this implementation makes one serializer depends on the other, but it works for my case. Will 1.0.0 provide this DocumentSerializer (or similar) as 0.10 does with a the JSON:API Adapter?

Thanks for answering :)

[bf4]

Will 1.0.0 provide this DocumentSerializer (or similar) as 0.10 does with a the JSON:API Adapter?

probably... like I said, I'm building and extracting this out of our code, while talking to stakeholders in Rails and API-gems...

[thomasnal]

I have come to re-check some details in documentation and spotted the ideas at the top planned for AMS.

AMS is instrumental to our project, we use it heavily to keep sane view on serialization and keep the team producing clean code.

Some of the ideas are related to removing functionality that works perfectly currently therefore it is worry-some. I came to this PR to see background behind the decisions that I have not found. Is there other source where I can find rationals behind the decisions? Especially for removing that what works now?

DocumentSeriarlizer.new(UserSerializer.new(user)).as_json

This snippet looks backwards from what AMS does currently. However, perhaps it means that below will keep working? Can you please shed more light @bf4?

class Profile:UsersShowSerializer < ActiveModel::Serializer
  attributes ...
end

class User::UsersShowSerializer < ActiveModel::Serializer
  attribute :profile, :serializer => Profile::UsersShowSerializer
  ...
end

class UsersController < ApplicationController
  def show
    render json: user, status: :ok
  end
end