GSoC 2021: Series Entity for BookBrainz

Hi everyone, I am Akash Gupta, currently pursuing my undergraduate from Kalinga Institute of Industrial Technology. This summer, I participated in Google Summer of Code and developed a new feature — Series Entity— for the project BookBrainz.

I was mentored by Nicolas Pelletier (monkey on IRC) during this period. This post summarizes my contributions to the project and the experiences that I had throughout the summer.

How it all started?

My journey with MetaBrainz began in March 2021, and before GSoC period I made a decent amount of code contribution to BookBrainz.

Initially, I started with improving the BookBrainz UI and made the site more compatible with older version of some browsers. With time I delved more into the codebase and started fixing bugs like converting revision notes string URL to clickable links, inappropriate badge appearing in entity deletion revision and did some other code refactoring.

Apart from fixing issues, I gradually started implementing new features such as displaying public collections on entity pages, adding identifiers to the ElasticSearch index to search entities with identifier ID. And also helped in increasing the code coverage by writing detailed unit tests for some ORM models such as EntityRevision Models and LanguageSet Model.


For the GSoC, I made a proposal that was aimed at implementing the Series Entity feature for BookBrainz. A series is a sequence of separate works, authors, editions, edition groups, or publishers with a common theme. The theme is usually prominent in the branding of the entities in the series, and the individual entities will often have been given a number indicating the position in the series.

The original proposal I submitted to Google underwent some modifications as the project progressed, details of which can be found later in this post.

Community Bonding

Summer of Code started with the community bonding period. During this period, my mentor Nicolas Pelletier made sure that we define a clear path to move along with the project. The first step for me was to get hands-on with Bookshelf.js(ORM library). Bookshelf.js was a new technology for me so I spent some time during this period learning it and understanding the implementation of the ORM models and functions in the bookbrainz-data repository.

My mentor and I had discussions regarding the design of the database schema for the series entity and relationship attributes. After several discussions, we finalized the schema and were ready to code. Under the scope of my project, we needed to add two relationship attributes(number and position). But we made sure to design the schema in such a way that other relationship attributes could be added in the future without any extra work to do. All the while, I kept a frequent dialogue with my mentor to get as a team, clarify issues with the codebase, and further define our plan of action.

Coding Period

First Phase

The program coding period kicked off with making changes to the existing BookBrainz schema. I started with creating the tables for series entity and relationship attributes. Ten new tables were added to the existing bookbrainz schema.

Following this, I started working on the bookbrainz-data ORM repository. I defined and developed the data models, used to make queries to and manipulate the database using an object-oriented paradigm. After the data model implementation, I worked on the relationship attributes saving mechanism by creating functions for the creation and update of attributes. I also added detailed unit tests for each of these models and functions, to make sure the code works correctly.

The Series entity schema
The relationship attributes schema

Now that the database and ORM models were ready for us to work on, I started working on creating the series editor frontend components and setting up the server routes for creating series. Once the series editor was set up, I added some form validators for series section fields and added unit tests to make sure validations are working accurately. Once we had the frontend component ready to fill basic series data, I added the new the relationship attributes mechanism to our entity editor. 

Following, this I started working on developing other web server routes for series such as the edit and delete routes, which allows users to edit and delete a series.

After we had the basic webserver routes to perform create, delete and update operations, I created the series display page and implemented the series GET route which would fetch the data for the requested series BBID and display them on the page.

The Series display page

I also created some test helper functions and added tests for the Series Entity main GET routes. I also worked on creating the series table component and extended the collection feature to include series.

Second Phase

The second phase of the coding period began with adding series endpoints to the BookBrainz API. I started with creating the lookup request endpoint which fetches the basic information of the series and, the browse and search request endpoints to search for or fetch series linked with other entities. I added the tests for the series API endpoints to make sure everything was working as per expectations.

The API Series endpoints

Subsequently, I created the series and relationship attributes revision formatters. This detects the change and formats the differences to display the full revision history of the series and attributes on the revision page.

After this, I added achievements for series creations. Anyone who creates a series entity gets the Series Creator badge as an achievement. I also added unit tests to make sure the code works fine and the badges are awarded correctly to the editor.

Following this, it was time to research what identifiers could be used for Series entities. After some research and feedback from the community members, I decided to add Wikidata, MusicBrainz, Goodreads, IMDB and VIAF as the identifier types for Series entity. I created a migration script to add these identifiers to the existing identifier_type table and did the necessary changes to display them in the frontend.

With the current implementation, we encountered some limitations like we were not able to link other relationship types to the series other than the series entity type. To overcome this, my mentor proposed to develop a new series component that would be used to add series items separately from the relationship editor. For this, I needed to revert the previous changes of the relationship editor and redefine the series section of the entity editor. I started implementing the new series editor component, which allows users to search for an entity and add it to the series directly on the series creation/edit page. After this, I worked on implementing the sorting algorithm to sort the items in series. A natural sort is performed on the number attribute of the series items when the ordering type is Automatic, and for Manual ordering, I developed the drag and drop sortable component that offers more control over the ordering of the items in the series, in any way the user wants.

The new series editor component

As a final step, I added the merge entity tool for the series. This allows users to merge duplicate series instead of deleting them, making sure we didn’t lose any data.

The Series Entity feature is deployed and available on the BookBrainz test site. Everyone is invited to test it and any feedback is welcome! We also have a short guide on how to use the new series entity for the curious. We plan to release this feature on the BookBrainz beta site very soon, after an initial phase of testing.

Overall Experience

To say the least, this has been a highly rewarding experience. I extend my most sincere gratitude to Google for running such a great and extremely inclusive program, Google Summer of Code has been a great opportunity for me. I learned new technical concepts everyday and it has made me a stronger software developer today. I had a wonderful time interacting with the amazing folks at MetaBrainz and especially it has been an absolute pleasure working with my mentor, Nicolas Pelletier. He has been constantly guiding and helping me throughout this journey, undoubtedly the best mentor anyone could ever ask for!

Truly an experience I will cherish for a lifetime!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.