GSoC 2021: Push the URL relationship editor to the next level

Hello everyone, I’m Yang Yang (aka yyoung), an undergraduate student from Shanghai Jiao Tong University, China. I am honored to be accepted as a student of Google Summer of Code 2021 in MetaBrainz Foundation to work on the improvements of external links editor. I had a good time with the MusicBrainz dev team this summer, and it was a valuable experience for me. This is a final report and overview of my work.

Overview

Several years ago, I dropped into MusicBrainz while searching on the Internet, but didn’t become a frequent user.

When I was preparing for GSoC this year, I found MetaBrainz Foundation, got to know the whole *Brainz family, and was surprised that it’s such a large and great project for music lovers.

I decided to apply, worked on small patches, got my PRs merged, joined IRC channel, and received a warm welcome. Then I drafted a proposal, posted it on the forum, improved it according to feedback, and finally got accepted.

In the past ten weeks, I improved the UI, refactored legacy code, implemented new features, worked with other team members, attended weekly meetings, did translation, participated in forum discussions, started editing on MusicBrainz, met people with the same favor of music, and now I’m moving all my playlists to MusicBrainz collections. I’m glad that I’ve chosen MetaBrainz.

Achievements

All my pull requests are available here.

Show changes made to external link by cleanup

All external links entered in the editor will go through an automatic cleanup process. However, the cleanup process is not perfect. Sometimes bugged or outdated rules produce the wrong result. Besides, the process is implicit for editors and will interfere with user input.

To solve these problems, I implemented a new popover dedicated to URL editing, in which the raw input and the cleaned-up output are in separate fields for easy comparison.

In preparation for future improvements like link highlights, the URL input boxes in the list are replaced with clickable links. Now that there’s a clickable link, the link in the tooltip of relationship type description can be safely removed, solving the text overflow issue (MBS-11795).

This is mainly implemented in PR #2151 and improved in PR #2114. It solves MBS-11391 and does part of MBS-11521 by extracting error-checking code as a reusable function in this commit.

Grouping external links by URL

Formerly, the external links editor already supports pasting a link several times to add multiple relationships, but the UI does not make that clear and straightforward. Also, it requires double editing to change a URL that has two relationships.

As a solution, I rearranged the layout to display the relationships as a list under the URL. When pasting an existing URL again, a notice will appear as a reminder. After confirmation, these links will be merged. Also, a new “Add another relationship” button is provided for appending more relationships, which is shown only when possible.

Since the relationships are placed under the link, the position of the error message also needs adjustments. This is accomplished by adding an extra attribute to indicate the target of the error message, and is implemented in PR #2128.

PR #2114 covers this improvement and solves MBS-11680.

Add links with begin & end dates

While MusicBrainz allows date period attributes (begin & end dates, ended flag) on URL relationships, these attributes can be modified from URL editing page only, but not from external links editor on other pages. Editors will need to create two edits if they want to add a link with these attributes, and some unaware editors ignore these attributes and directly remove or replace the link when it’s ended. That is a great inconvenience for users and has been there for nearly a decade.

This summer I enabled the display of these attributes in the editor, and implemented a dialog that resembles the relationship editor counterpart to set these attributes in a simple way.

This feature is implemented in PR #2219 and it solves MBS-12074.

Support auto-selection & validation of multiple relationships

Apart from the layout, link type auto-selection and validation also need to support multiple relationships.

Previously we can only auto-select and validate one relationship type for a single URL, but this is becoming insufficient as there’re more and more situations where external links have more than one role. For example, an archive.org page may act as “other databases” as well as “lyrics” or “score”; Jamendo always provides “free streaming” and “free download”, thus these two types should be automatically selected. But due to the structure of URL cleanup entries, a site cannot be added to lyrics whitelist while being allowed as other types.

To overcome the limitations of the old mechanism, I designed a new one based on that and refactored URL cleanup. First, I extended the definition of the allowed types from one type to multiple types in an array. Then, I improved auto-selection to support selecting multiple types and allow an extra function to implement custom logic. Finally, I added a function to validate combinations of multiple relationships after passing every single validation.

To demonstrate the new mechanism, I fixed STYLE-1466 and MBS-8932 as examples.

Apart from those, I enhanced the link type selector to show valid types only for a better user experience.

The features above are implemented in PR #2184. They resolve MBS-9902, STYLE-1466, and MBS-8932.

Other improvements & side products

Challenges & Experience

At the start, the biggest challenge for me is the large codebase full of unfamiliar code and structure. There’re more than 1000 files, and the mix of templates and React components is far from what I’m familiar with. Thankfully, there’s brief documentation on the folder structure. After working on some small patches, I finally get a better understanding of it. In the next few weeks, I gradually get the hang of it by reading and learning from other people’s code. And finally, I’m able to write comments for existing code, spot flaws in it, and eventually refactor it. What I benefit most from the experience is that it gave me the confidence to jump out of my comfort zone and dive into big, real-world projects.

Another big challenge is backward compatibility, both in the code and in the workflow that users are accustomed to. There’s a major difference between making improvements and implementing new features — in the former one, you have to be careful not to break something else. In terms of UI and workflow, I’m always trying to adapt to existing workflows, and opened a thread on the forum asking for feedback from users. Though there might not be the best result even after a long discussion, the encouraging words and acceptance from the community have always been my motivation, it’s much more fun than maintaining a personal project.

Possible Future Work

  • Support bypassing bugged and outdated cleanup rules (MBS-4684, MBS-9040)
  • Add highlights to the links displayed in the editor to indicate addition, modification, or deletion (MBS-11901)
  • An option to view all valid relationship types and type combinations in the error message (MBS-11899)
  • Support setting all relationship begin/end dates of a link at once (MBS-11894)

Special Thanks to

  • My mentor yvanzo, for his patience, help, and guidance, our meetings are always constructive and inspiring.
  • reosarevok and bitmap, for offering generous help and reviewing my pull requests to make it better.
  • Freso, for directing the dev meeting every week, presenting my mailed-in reviews, and making meeting notes afterward.
  • CatQuest and other MusicBrainz editors who actively give feedback and advice on the new UI.
  • akshaaatt and other students who are also making MetaBrainz even better.
  • MetaBrainz Foundation and Google Summer of Code, for providing me the chance to engage in this amazing community and experience the wonderful open-source culture.

3 thoughts on “GSoC 2021: Push the URL relationship editor to the next level”

Leave a Reply

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

WordPress.com Logo

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

Google photo

You are commenting using your Google 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.