Difference between revisions of "Development/Summer of Code/2022/BookBrainz"

From MusicBrainz Wiki
Jump to navigationJump to search
(Added link to good-first-bug ticket)
 
(13 intermediate revisions by 4 users not shown)
Line 5: Line 5:
 
<span style="font-size:smaller">(see also: [[Development/Summer_of_Code/Getting_started|Getting started with GSoC]])</span>
 
<span style="font-size:smaller">(see also: [[Development/Summer_of_Code/Getting_started|Getting started with GSoC]])</span>
   
The first thing to do to get started with BookBrainz is to clone the bookbrainz-site [https://github.com/BookBrainz/bookbrainz-site GitHub repository], and follow the README.md file and [https://bookbrainz-dev-docs.readthedocs.io/en/latest/docs/installation.html our developer documentation] to get the site up and running on your computer.
+
The first thing to do to get started with BookBrainz is to get familiar with the website and start editing (the [[bb:help|help page]] and [https://bookbrainz-user-guide.readthedocs.io/en/latest/ user guide] are good starting points).
   
We have a testing website at [https://test.bookbrainz.org test.bookbrainz.org] with its own separate database. You can create an account there and use it to get familiar with the website and database without fear of adding inadequate data.
+
We also have a testing website at [https://test.bookbrainz.org test.bookbrainz.org] with its own separate database. You can create an account there and use it to get familiar with the website and database without fear of adding inadequate data.
  +
  +
The next step is to clone the bookbrainz-site [https://github.com/BookBrainz/bookbrainz-site GitHub repository], and follow [https://bookbrainz-dev-docs.readthedocs.io/en/latest/docs/installation.html our developer documentation] to get the site up and running on your computer.
  +
  +
When you feel ready to try your hand on some bugs, we have “good first bug” category on our ticket tracker: https://tickets.metabrainz.org/issues/?filter=11910
   
 
Come and speak to us in the BookBrainz [[IRC]] ([https://kiwiirc.com/nextclient/irc.libera.chat/?#bookbrainz Libera.Chat/#bookbrainz]) if you finish all of that, or get stuck at any point!
 
Come and speak to us in the BookBrainz [[IRC]] ([https://kiwiirc.com/nextclient/irc.libera.chat/?#bookbrainz Libera.Chat/#bookbrainz]) if you finish all of that, or get stuck at any point!
Line 19: Line 23:
   
 
Proposed Mentors: ''Monkey''<br>
 
Proposed Mentors: ''Monkey''<br>
Languages/skills: User interfaces, User Experience, React, Node.js
+
Languages/skills: User interfaces, User Experience, React, Node.js<br>
  +
Estimated Project Length: 350 hours<br>
  +
Difficulty: hard<br>
  +
Expected outcomes: A new user-friendly entity creation page and routes, thoroughly tested and debugged
  +
   
 
[https://community.metabrainz.org/c/bookbrainz Forum for discussion]
 
[https://community.metabrainz.org/c/bookbrainz Forum for discussion]
Line 25: Line 33:
 
This project requires a solid knowledge of the BookBrainz schema and edit pages.
 
This project requires a solid knowledge of the BookBrainz schema and edit pages.
   
As each entity has a separate creation page, users are faced with a complex workflow for simple use cases (such as 'adding a book I have') with lots of repeatition (for example the title of a work repeated for an edition and an edition group, in a simple use case of a book), increasing chances of making errors.
+
As each entity has a separate creation page, users are faced with a complex workflow for simple use cases (such as 'adding a book I have') with lots of repetition (for example the title of a work repeated for an edition and an edition group, in a simple use case of a book), increasing chances of making errors.
   
 
Such a basic workflow should be a lot more straightforward (especially for inexperienced users). The goal of this project is to design and implement a single form that will improve the editing experience.
 
Such a basic workflow should be a lot more straightforward (especially for inexperienced users). The goal of this project is to design and implement a single form that will improve the editing experience.
Line 64: Line 72:
   
 
Proposed Mentors: ''Monkey''<br>
 
Proposed Mentors: ''Monkey''<br>
Languages/skills: SQL, Node.js, knowledge of BookBrainz schema
+
Languages/skills: SQL, Node.js, knowledge of BookBrainz schema<br>
  +
Estimated Project Length: 350 hours<br>
  +
Difficulty: hard<br>
  +
Expected outcomes: A back-end system to parse and import large scale databases, importing Bookogs
   
 
[https://community.metabrainz.org/c/bookbrainz Forum for discussion]
 
[https://community.metabrainz.org/c/bookbrainz Forum for discussion]
Line 80: Line 91:
   
   
  +
=== Administration system ===
=== Add subscriptions and email notifications ===
 
   
 
Proposed Mentors: ''Monkey''<br>
 
Proposed Mentors: ''Monkey''<br>
Languages/skills: Node.js, SQL
+
Languages/skills: Node.js, SQL, ExpressJS<br>
  +
Estimated Project Length: 175 hours<br>
  +
Difficulty: easy<br>
  +
Expected outcomes: A usable administration system with arbitrary levels of privileges
   
 
[https://community.metabrainz.org/c/bookbrainz Forum for discussion]
 
[https://community.metabrainz.org/c/bookbrainz Forum for discussion]
   
Like [https://musicbrainz.org/doc/Subscription on MusicBrainz], users should be notified by default of new edits on an entity they edited. This allows users to verify new edits to entities they know and improves quality of the data overall.
 
   
  +
BookBrainz currently has no administration system, or any good way of giving users special privileges.
The aim of this project is to allow users to subscribe to entities and receive e-mail updates of new edits for that entity.
 
  +
This certainly needs to change!
This will require:
 
  +
* Supporting subscriptions in the database schema ([https://github.com/bookbrainz/bookbrainz-site/tree/master/sql SQL], [https://github.com/bookbrainz/bookbrainz-data-js Node ORM])
 
  +
For this project, you will be devising and implementing a basic admin system allowing for a flexible privilege hierarchy.
* Implementing endpoints for users to subscribe/unsubscribe to entities ([https://github.com/bookbrainz/bookbrainz-site/blob/master/src/server/routes/editor.js ExpressJS])
 
  +
* Adding a button on the entity pages to subscribe/unsubscribe ([https://github.com/bookbrainz/bookbrainz-site/blob/master/src/client/components/pages/entities/author.js React])
 
 
This will require at minimum:
* Implement a mailing library on the server ([https://www.npmjs.com/package/nodemailer Node])
 
  +
* Modifying the database schema, adding at least:
* Devise and implement a mechanism to know when and to whom to send mails
 
  +
** a table to define roles
  +
** a table to attach users to roles
  +
* Implementing a simple admin panel webpage to allow admins to search for users, give users privileges and take other actions
  +
* Middleware for securing specific routes according to a user's roles:
  +
** admins can view the admin panel
  +
** admins can block or deleted abusive users
  +
** privileged editors can edit relationships and identifiers
  +
** privileged editors can trigger a reindex of the search server
   
 
Extended goals:
 
Extended goals:
  +
* a page to allow privileged users to edit and add relationships and identifiers
* Allow users to choose whether to be automatically subscribed to entities they edit, and how often
 
  +
* a public log of administration actions (see for example [https://critiquebrainz.org/log the CritiqueBrainz admin log])
* The above goal requires to create a user preferences page
 
  +
  +
  +
=== CritiqueBrainz reviews for BookBrainz entities ===
  +
  +
Proposed Mentors: ''Monkey'', ''Alastair''<br>
  +
Languages/skills: Python, Flask, SQL, ReactJS<br>
  +
Estimated Project Length: between 175 and 350 hours<br>
  +
Difficulty: medium<br>
  +
Expected outcomes: Users can write, submit and display reviews for BookBrainz entities both on critiquebrainz.org and bookbrainz.org
  +
  +
CritiqueBrainz gives users a way to write Creative Commons licensed reviews and ratings linked to MusicBrainz.
  +
If an entity is in MusicBrainz, you can review it on CritiqueBrainz.
  +
  +
Considering the importance of book reviews in the literature world, we would like to extend CritiqueBrainz to allow users to review BookBrainz entities.
  +
There are a lot of similarities between the sister projects MusicBrainz and BookBrainz, which makes it possible for us to extend the infrastructure of CritiqueBrainz to support both.
  +
  +
This project would be implemented partly on the CritiqueBrainz side using python, and partly on the BookBrainz side using React/javascript).
  +
  +
On the CritiqueBrainz side, you would
  +
* support connecting to the BookBrainz database
  +
* load BookBrainz entities and required data (via SQL queries)
  +
* extend the CritiqueBrainz project to support new entity types from BookBrainz. CritiqueBrainz already supports different types of items from MusicBrainz (Artist, Release, Event, etc), and so already has the infrastructure in place to add new items.
  +
**Author, Work, Edition Group, Series
  +
* Make any changes as necessary to change text that talks about Music and make it generically refer to Music and Books
  +
  +
On the BookBrainz side:
  +
* Implement oauth login to CritiqueBrainz
  +
* implement the front-end components to allow users to write and send reviews and ratings to CB
  +
* retrieve and display existing reviews and ratings for an entity on various pages (ostensibly Edition Group and Publishers)

Latest revision as of 12:59, 30 March 2022

This page will discuss the current list of suggested ideas for students to develop proposals for Google's Summer of Code for BookBrainz. If you're a student, feel free to base your proposal on one of these ideas, or pick and entirely new idea that you think might be useful to us.

Getting Started

(see also: Getting started with GSoC)

The first thing to do to get started with BookBrainz is to get familiar with the website and start editing (the help page and user guide are good starting points).

We also have a testing website at test.bookbrainz.org with its own separate database. You can create an account there and use it to get familiar with the website and database without fear of adding inadequate data.

The next step is to clone the bookbrainz-site GitHub repository, and follow our developer documentation to get the site up and running on your computer.

When you feel ready to try your hand on some bugs, we have “good first bug” category on our ticket tracker: https://tickets.metabrainz.org/issues/?filter=11910

Come and speak to us in the BookBrainz IRC (Libera.Chat/#bookbrainz) if you finish all of that, or get stuck at any point!

Ideas

Here are some suggestions of projects that would improve BookBrainz. Of course, suggestion means you're not limited to these ideas and can propose your own if after using BookBrainz you find a substantial area you can improve.

Design and implement a unified creation form

Proposed Mentors: Monkey
Languages/skills: User interfaces, User Experience, React, Node.js
Estimated Project Length: 350 hours
Difficulty: hard
Expected outcomes: A new user-friendly entity creation page and routes, thoroughly tested and debugged


Forum for discussion

This project requires a solid knowledge of the BookBrainz schema and edit pages.

As each entity has a separate creation page, users are faced with a complex workflow for simple use cases (such as 'adding a book I have') with lots of repetition (for example the title of a work repeated for an edition and an edition group, in a simple use case of a book), increasing chances of making errors.

Such a basic workflow should be a lot more straightforward (especially for inexperienced users). The goal of this project is to design and implement a single form that will improve the editing experience.

Some form of separation (like tabs) will be necessary to separate the different entities forms as steps. For each step, entities can be either searched for and selected, or created. While it would be best to show only the strict necessary fields for each step at first to limit clutter, users should have the full range of options of the current forms accessible easily. The form will automatically create the relevant relationships and links between the entities.

Keep in mind that "adding a book" is a simple case, and that we should be able to optionally enter more complicated cases (for example an anthology of short stories will have multiple Works, and the title of the Edition may be different from any of the Works it contains). Or an anthology of various Authors might be attributed on the cover to a single Author.

The first phase should be to make a mockup with a prototyping/wireframing tool (for example: Sketch, Figma, Pencil Project). We will work together iteratively during both the UX and implementation sections of the project.

Here are three example scenarios of different level users. The unified form should allow for each of them and provide the best user experience possible.

Scenario 1 User is new to BookBrainz and adding their first book. They don’t know what the different entities are, or what relationships are. The book to enter is a physical book the user has, a novel. The author’s name and title fo the book are on the cover.

Scenario 2 User has entered some books already for an author, The book is a collection of 20 short stories from that same author, written under a pen name. The pen name is on the cover, and the title of the book is different from the title of any of the short stories. The user has an ebook version and a paperback from another publisher borrowed from the library. The book is a translation, and the translator is well known and their name appears on the first page.

Scenario 3 User has been using BookBrainz for a long time and understands how all entities relate User has a series of magazines (35 issues) they want to add. The magazine has multiple editors


Import the (now defunct) Bookogs database

Proposed Mentors: Monkey
Languages/skills: SQL, Node.js, knowledge of BookBrainz schema
Estimated Project Length: 350 hours
Difficulty: hard
Expected outcomes: A back-end system to parse and import large scale databases, importing Bookogs

Forum for discussion

The sites Bookogs and Comicogs, sister projects of Discogs, have been closed in 2020; some editors elected BookBrainz to continue contributing open data.

The Bookogs database dumps were made publicly available for download in json format right after the closing of the project. In order to prevent the loss of Bookogs contributions we want to import all the entries from the database dumps, as discussed in this thread.

This will require processing very large json files in a robust manner, creating "adapters" to transform entities from one database schema to the other, allowing for repeating the process without duplicating entries. You will put together a detailed plan fo action ahead of time

Discussions are in progress for matching roles, formats and genres to BookBrainz' schema.


Administration system

Proposed Mentors: Monkey
Languages/skills: Node.js, SQL, ExpressJS
Estimated Project Length: 175 hours
Difficulty: easy
Expected outcomes: A usable administration system with arbitrary levels of privileges

Forum for discussion


BookBrainz currently has no administration system, or any good way of giving users special privileges. This certainly needs to change!

For this project, you will be devising and implementing a basic admin system allowing for a flexible privilege hierarchy.

This will require at minimum:

  • Modifying the database schema, adding at least:
    • a table to define roles
    • a table to attach users to roles
  • Implementing a simple admin panel webpage to allow admins to search for users, give users privileges and take other actions
  • Middleware for securing specific routes according to a user's roles:
    • admins can view the admin panel
    • admins can block or deleted abusive users
    • privileged editors can edit relationships and identifiers
    • privileged editors can trigger a reindex of the search server

Extended goals:

  • a page to allow privileged users to edit and add relationships and identifiers
  • a public log of administration actions (see for example the CritiqueBrainz admin log)


CritiqueBrainz reviews for BookBrainz entities

Proposed Mentors: Monkey, Alastair
Languages/skills: Python, Flask, SQL, ReactJS
Estimated Project Length: between 175 and 350 hours
Difficulty: medium
Expected outcomes: Users can write, submit and display reviews for BookBrainz entities both on critiquebrainz.org and bookbrainz.org

CritiqueBrainz gives users a way to write Creative Commons licensed reviews and ratings linked to MusicBrainz. If an entity is in MusicBrainz, you can review it on CritiqueBrainz.

Considering the importance of book reviews in the literature world, we would like to extend CritiqueBrainz to allow users to review BookBrainz entities. There are a lot of similarities between the sister projects MusicBrainz and BookBrainz, which makes it possible for us to extend the infrastructure of CritiqueBrainz to support both.

This project would be implemented partly on the CritiqueBrainz side using python, and partly on the BookBrainz side using React/javascript).

On the CritiqueBrainz side, you would

  • support connecting to the BookBrainz database
  • load BookBrainz entities and required data (via SQL queries)
  • extend the CritiqueBrainz project to support new entity types from BookBrainz. CritiqueBrainz already supports different types of items from MusicBrainz (Artist, Release, Event, etc), and so already has the infrastructure in place to add new items.
    • Author, Work, Edition Group, Series
  • Make any changes as necessary to change text that talks about Music and make it generically refer to Music and Books

On the BookBrainz side:

  • Implement oauth login to CritiqueBrainz
  • implement the front-end components to allow users to write and send reviews and ratings to CB
  • retrieve and display existing reviews and ratings for an entity on various pages (ostensibly Edition Group and Publishers)