public_activity: the licence file is named MIT-LICENSE, and the badge points at a third account

The repository, the badges and the gem carry three different names

The repository sits under an organisation with a hyphenated name and a separated project part. The distribution name is the joined form, which is also what you put in a Gemfile. And the code quality badge at the top of the readme points at a third account entirely, one that is neither the organisation nor obviously the maintainer. So the badge a reader sees first belongs to a different path than the code it is rating. The screencast credited in the file is a third naming artefact again: the canonical walkthrough is an episode of a long-running video series, which is a useful introduction and also a document that predates every version currently installable.

The licence file is named MIT-LICENSE rather than LICENSE

The top level listing holds a file whose name encodes the licence rather than the word licence. That is a perfectly ordinary convention and several projects do it, but it is not the convention that automated tooling assumes. Gem specification tooling, licence scanners and corporate allowlist checkers look for a file called one thing or the other, and a repository that spells it differently can end up reporting no licence detected on a package whose metadata claims one. Here the situation is compounded slightly by the file naming in the rest of the tree: there is a gemspec, a Rakefile, an editor project file and a continuous integration configuration sitting alongside it, so the licence is the least conventionally named of the lot. Worth confirming what your own tooling sees before shipping a dependency on it.

Issues on unsupported versions are closed and pull requests are refused

The version support section is short and unusually firm. The current line supports a recent Ruby and Rails combination, and there is an older line for people who cannot upgrade yet, with the boundary stated as a Ruby version at or below two point seven and Rails five or later. Then comes the sentence that shapes what the project is worth to you: issues relating to the unsupported combinations will be closed without resolution, and pull requests will not be accepted. That is a legitimate policy for a small gem, and it is also a hard constraint. It means the decision about whether to upgrade Ruby is effectively made for you, and a team on an old stack has a library that documents its behaviour but will not debug it.

An activity layout is a partial, and it has to be named like one

The display layer is where this gem's sharp edges are, and the documentation is honest about them. Rendering takes options that are passed down to the partial renderer, and the documented use for them is wrapping a group of activities in a shared frame carrying a timestamp or an avatar. That frame is called a layout, and it is looked up in the layouts directory by name:

<%= render_activities(@activities, layout: :activity) %>

But the file it looks for is the form of a partial, and the readme marks this as important: layouts for activities are also partials, hence the prefix that marks a partial. So a file called activity.erb in the layouts directory is invisible to the gem, and the failure is a template that cannot be found rather than a clear error about a layout. The naming of the helper compounds it. One helper renders a single activity, a plural one is documented as an alias that does the same, and both can also be written as a method on the activity object taking the view context.

Two years separate the two visible 3.x releases

The release history is thin and uneven. The newest visible version was published in January of this year. The one before it in the visible list is the 3.0.0 release from January 2024, and before that a 2.x release from July 2022. So the two most recent points in the history are two years apart, with a patch release appearing in the gap that is not among the three shown. The current line therefore arrived as a major version, sat for two years, and picked up a patch. The commit history has been steadier than the release history: the last push to the default branch is about four months old, so work has continued since the January release without a new tag. For a gem that follows the framework it plugs into, that gap is worth checking against your own Rails version before you pin.

Migrations are generated for one of the three supported object mappers

The gem supports three persistence layers and picks between them with a single line in an initializer. Active Record is the default and needs no configuration. The other two each get a short block naming the mapper:

PublicActivity::Config.set do
  orm :mongoid
end

The documentation is explicit about the consequence for one of them: creating the migration for the activities table and running it is marked as applying to Active Record only. So a project on either of the alternative mappers gets the tracking, the rendering and the helpers, and writes its own migration. The model configuration examples make the same asymmetry visible, since the Active Record version inherits from an Active Record base class while the other two inherit from their document base and are otherwise identical. And the alternative mappers are named by major version, one of them at a version line several majors behind.

Local variables must not be passed through the options hash, because activity parameters are stored

Passing extra data into a rendered activity is done through a locals option, and the readme explains why that is the only supported route:

<%= render_activity(@activity, locals: {friends: current_user.friends}) %>

Before a particular version, you could pass those variables directly into the same options hash the render method uses and read them back out from the activity's parameters. That route still works, but it is not preferred, and the stated reason is a bug class rather than a style preference: it prevents variables from shadowing the activity parameters that live in the database. In other words the older form mixed caller data and persisted data in one namespace, which is the shape of bug that surfaces much later and far from its cause. It is also why the testing section tells you to turn the gem off in your suite before asserting on your own code, rather than letting it record fixtures.

A continuous integration file and an editor project file sit at the root

Two entries in the top level listing are worth a second look. The first is a continuous integration configuration for a hosted service, present in the tree even though the badge at the top of the readme advertises a different service entirely, so the file a maintainer maintains and the status a reader sees are two different things. The second is an editor project file, checked in at the repository root, which pins workspace settings for one specific editor and is of no use to anyone else; it is the kind of file that gets added once and never removed. Two directories deserve a mention alongside them. One holds a dependency appraisal configuration, which is how the gem tests against more than one set of library versions, and the other is the test suite itself. The presence of an appraisal setup alongside three supported mappers is the clearest sign of how wide the test matrix actually is.

Editorial conclusion

Adopt this if you want a public activity feed on an existing Rails application and you are on a supported Ruby and Rails combination, because the alternatives in that space have not changed much. Two things to check before you wire it in. The activity layout is a partial wearing a layout's name, so a file without the leading-character prefix produces a template that cannot be found, and the render helpers have three interchangeable names that are easy to confuse. And the gem supports three object mappers but only generates migrations for one, so if you are on either of the other two you own your schema.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. public-activity/public_activity on GitHub
4. README
5. Releases