GSOC-2020: Unified Creation Form-BookBrainz: Prabhleen

GSoC 2020 Proposal

Prabhleen Kaur
MB username: Sehaj
E-mail: prabhleenkaur.sehaj@gmail.com
Github: prabhleenkaur1007
Town, Country: Delhi, India
Time Zone: (GMT+05:30) Kolkata

Design and Implement a Unified creation form

Overview:
The current design of forms for create pages lack the straightforward, simplified, error-free editing of entities. It has a complex workflow and produces redundant data. Such a workflow should rather be complete and simple for users to limit clutter (For example: Under present scenario the title of the work is repeated in edition and edition-groups).
My aim is to improve the user-experience, add necessary and complete information with reduce repetition.
I will use the following frameworks for development:
Node.js, React, Semantic UI, Bootstrap

I plan to add the following features:

  1. A Book(single work or collection) can now be created having an author, publisher, edition and additional information like alias, identifier and disambiguation in a single straight manner.
  2. More than one edition can be added at the time of book creation or while editing.
  3. If a client adds a book by an author, then the backend will link the entities and hence add relevant relationship.
  4. At the time of creation, if any author or publisher already exists, then the details are not required to be added again (though the user can edit them any time), otherwise the client will have to create a new one first.

All the backend code required for this is already present in the current forms, it just needs a refactoring, some addition and some deletion.

Full Description:

ā€¢ Here the type of the book will include: novel, magazine, leaflet etc.
image
This part will reuse the function WorkAttributes under src/cient/components/pages/entities/work.js.

ā€¢ Now the server asks what type of book user wants to enter:

  1. If it is a single work, then client will be asked to enter the details on the next page.
  2. If it is a collection, then client will be asked about the number of authors.
    a. If the author is same for all works then, the client will be asked to enter their names.
    b. If the authors are different the client will be asked to enter the work name along with author.
    image

This page will create new const for storing the number of works in book (single or collection), and reuse the existing for the author type. (person or group)
Add getNumTypeAttribute in src/client/helpers/entity.js:

export function getNumTypeAttribute(workNumtype){
    return {data: extractAttribute(workNumtype, 'label'), title: 'Number of Works'}; 
}

function BookAttributes({book, work, author}) {
    if (book.deleted) {
        return deletedEntityMessage;
    }
    const numOfWorks = getNumTypeAttribute(work.workNumType).data;
    const authorType = getTypeAttribute(author.authorType).data;
   const type = getTypeAttribute(book.bookType).data;
    const languages = getLanguageAttribute(book).data;
    const sortNameOfDefaultAlias = getSortNameOfDefaultAlias(book);
    return (
        <div>
            <Row>
                <Col md={2}>
                    <dl>
                        <dt>Sort Name</dt>
                        <dd>{sortNameOfDefaultAlias}</dd>
                    </dl>
                </Col>
                <Col md={2}>
                    <dl>
                        <dt>Type</dt>
                        <dd>{type}</dd>
                    </dl>
                </Col>
                <Col md={2}>
                    <dl>
                        <dt>Language</dt>
                        <dd>{languages}</dd>
                    </dl>
                </Col>
		   <Col md={2}>
                    <dl>
                        <dt>Number Of Works</dt>
                        <dd>{numOfWorks}</dd>
                    </dl>
                </Col>
		   <Col md={2}>
                    <dl>
                        <dt>Author Type</dt>
                        <dd>{authorType}</dd>
                    </dl>
                </Col>

            </Row>
        </div>
    );
}
BookAttributes.displayName = 'BookAttributes';
BookAttributes.propTypes = {
    book: PropTypes.object.isRequired
};

ā€¢ Next, the author and publisher can be created using +New button or if they already exists, then it can be searched.
image
For an anthology by different authors (collection of works), the name on the cover page can be any one of them.

All the information to be input on this page will come from following sources:

src/client/entity-editor/validators/base.js

export function validateRequiredString(value: any): boolean {
if (!_.isString(value)) {
return false;
}

return Boolean(value);

}

src/client/entity-editor/validators/common.js

export function validateNameSectionName(value: any): boolean {
return validateRequiredString(value);
}

src/client/entity-editor/validators/author.js

export function validateForm(
formData: any, identifierTypes?: ?Array<_IdentifierType>
): boolean {
const conditions = [
validateAliases(get(formData, ā€˜aliasEditorā€™, {})),
validateIdentifiers(
get(formData, ā€˜identifierEditorā€™, {}), identifierTypes
),
validateNameSection(get(formData, ā€˜nameSectionā€™, {})),
validateAuthorSection(get(formData, ā€˜authorSectionā€™, {})),
validateSubmissionSection(get(formData, ā€˜submissionSectionā€™, {}))
];

return _.every(conditions);

}

The above functions will be required to check if the author is already present or not. Similarly it can be performed for publisher.

Other additional information can be added using buttons like Add Physical Data and Add New Edition(used in case the user wants to add more than one editions).
A user can add book, and the related editions can be either created at the time of book creation or by going on the edit page for that book.

The code for adding release-date, edition-format and physical data can be collected from:

src/client/helpers/entity.js

export function getEditionReleaseDate(edition) {
const hasReleaseEvents = edition.releaseEventSet &&
edition.releaseEventSet.releaseEvents &&
edition.releaseEventSet.releaseEvents.length;

if (hasReleaseEvents) {
    return transformISODateForDisplay(edition.releaseEventSet.releaseEvents[0].date);
}

return '?';

}
export function getEditionFormat(entity) {
return (entity.editionFormat && entity.editionFormat.label) || ā€˜?ā€™;
}

src/client/components/pages/edition.js

const format = extractAttribute(edition.editionFormat, ā€˜labelā€™);
const pageCount = extractAttribute(edition.pages);
const weight = extractAttribute(edition.weight);
const width = extractAttribute(edition.width);
const height = extractAttribute(edition.height);
const depth = extractAttribute(edition.depth);

const releaseDate = getEditionReleaseDate(edition);

ā€¢ These editions for the books will have details like: language, publisher, format, release date which might be different from one another, but all of the editions will have a system generated naming system, like Serial number ā€“ Format ā€“ Year.
Also every term on every page will have tooltip to declare and define their meaning in database. This will be important and useful for first time users
To create new edition, no new code will be written as declaring a book is like declaring first edition only.
image

Similarly, new author and new publisher can be create like below:
image
image

The backend code to generate new author and publisher will be same except:
ā€¢ No new name, sort-name, language, alias, identifier, disambiguation.
ā€¢ It will only consist of additional information if we compare it to present forms.

image

These fields will use the code for entity-type work which takes the input for alias, identifier and disambiguation.
src/client/entity-editor/alias-editor/alias-editor.js
src/client/entity-editor/alias-editor/alias-row.js
src/client/entity-editor/identifier-editor/identifier-editor.js
src/client/entity-editor/identifier-editor/identifier-row.js
src/client/entity-editor/name-section/disambiguation-field.js

This page will be on user screen everytime a user wants to enter a new book, author or publisher or edits the same. (This can be used to solve the problem of adding a pen name for an already existing author)

ā€¢ Here the optional information can be added or left blank (as per userā€™s choice) and then the creation form can be submitted.
image

ā€¢ The backend code to link enities will use:
src/client/entity-editor/relationship-editor/relationship-editor.js

renderEntitySelect() {
const {baseEntity, relationshipTypes} = this.props;
const types = getValidOtherEntityTypes(relationshipTypes, baseEntity);
if (!types.length) {
return null;
}
const typesForDisplay = types.map(_.startCase);
const lastType = _.last(typesForDisplay);
const otherTypes = _.join(typesForDisplay.slice(0, -1), ', ');
const label =
Other Entity (${otherTypes.length ? ${otherTypes} or : ''}${lastType});
return (

);

Here the base-entity will always be book and target entity will be, AUTHOR or PUBLISHER.

On the main book page, the editions and relations list will have links.
image

This is the workflow that I intend to perform:

Testing:
During coding period, I will push daily commits and send weekly pull requests. I will share screenshots to show the actual working of the work done.
In the community bonding period, I will learn more about react and will actively talk to community.

About Me:
I am a 2nd year undergraduate student pursuing B.Tech in IT from Maharaja Surajmal Institute Of Technology(GGSIPU). Previously I have done an internship under a start-up named ā€˜IndieCorpā€™ as a Web-Developer an have been participating in hackathons. I am also a core member of International Organisation Of Software Developers in my college. We are a team of 200+ developers and we actively work on projects, organise meetups and create an agile tech. environment in the institute.
Tell us about the computer(s) you have available for working on your SoC project!
I have DELL laptop with i3 processor with 4gb of ram.

When did you first start programming?
I started programming in my first year of College only. I was a medical student in my school.

What type of books do you read?
I enjoy reading fantasy and inspirational novels like Harry Potter and The Alchemist are my favourite. Iā€™ve also read classics Little Women.

Have you contributed to other Open Source projects? If so, which projects and can we see some of your code?
Iā€™ve contributed to Bookbrainz only. I will update my PRs in a day or two.

What type of programming projects have you worked on?
Last summer i worked on a network communicator project using socket programming in c++ with a help of mentor from Learn-IT-Girl.

How much time do you have available, and how would you plan to use it?
I am free all summer except for about last 20 days. My college resumes in August. In that time also I will be able to give 3-4 hours a day easily. Also I will be having exams in coming may-mid but due to ongoing coronavirus, nothing is sure.
I plan to give 30-35 hours a week in the project. :slightly_smiling_face:

I will update the timeline and PRs soon.
@mr_monkey, please review my proposal and suggest the changes.

Any suggestions from fellow contributors will always be appreciated.

Any updates, suggestions or reviews? @mr_monkey

Hi @Prabhleen!

Thanks for your proposal !
Generally, I think you have the right approach regarding user experience.
I like that you worked on a workflow, I think it clarifies the intent and itā€™s the right way to visualize it.

First off a couple of general reactions:

  • The unified form comes as an addition, not a replacement to the existing entity-editor.
  • If I understand correctly, you mention a new entity type ā€˜Bookā€™; that is not what we are looking for here. The existing entities should be unchanged, and itā€™s only data entry that should be improved. Beginner users will have an idea of what ā€œa bookā€ is and it takes some knowledge of BookBrainz to understand how to break it down into the existing entities and relationships. The goal of this project is to bridge that divide.
  • The code for entity-editor is quite complex both on the back- and front-end. Thereā€™s a lot of moving parts and you need to understand everything well enough to change or refactor it. I know it took me a few months when I started. I see no mention of Redux, for example, which is used to manage state in the entity editor and is crucial for any entity creation. That part wonā€™t be straightforward.
  • At first glance, I would say the scope of the project seems too big considering you wonā€™t be available for the last three weeks and your level of experience of the codebase. In general, I see too little technical details in the proposal and Iā€™m worried you wonā€™t have the time to learn the codebase AND develop the new form.
  • There is no indication on the mockups of where in the process the user is, or how they can go back to previous sections.
  • I also think a summary page before submission would be a good idea. It would present all the entities being created/linked together, for the user to review.

Now for more details:

I will use the following frameworks for development: Node.js , React , Semantic UI , Bootstrap

Considering we donā€™t currently use Semantic UI but Bootstrap instead, why add Semantic UI? Iā€™m worried they would get in each otherā€™s way too (naming conflicts and such).

Now the server asks what type of book user wants to enter:

The mockup there I find difficult to understand, as all the possible states are displayed at the same time. Iā€™d like to see the various cases separately to have a better idea. As a rule of thumb, a mockup should only ever show what the user will see.

This part will reuse the function WorkAttributes under src/cient/components/pages/entities/work.js

This component is only used for displaying entity details, not for editing them. The same goes further down for components/pages/edition.js
Considering we ultimately want to keep the existing entity-editor pages, which components will you be able to reuse, and how?

The above functions will be required to check if the author is already present or not. Similarly it can be performed for publisher.

The validators you pasted are there, as their name suggest, to validate the input data. It is not used to determine if an entity of the same name already exists.

For that mechanism, have a look at the checkIfNameExists Redux actions that is dispatched by the name section: https://github.com/bookbrainz/bookbrainz-site/search?q=checkIfNameExists and how it is then used in the entity editor: Repository search results Ā· GitHub

[ā€¦] all of the editions will have a system generated naming system, like Serial number ā€“ Format ā€“ Year .

Does that mean the name for these editions is set automatically to that name? If so I donā€™t think thatā€™s a good solution, and it departs from the existing guidelines (Editions have the ā€œtitle of the bookā€ as their name).
However for display purposes only, such a name could be generated from the information entered for that Edition.

To create new edition, no new code will be written as declaring a book is like declaring first edition only.

I donā€™t understand this statement. Could you please rephrase it?

I think there should be no need at this point to edit the ā€˜languageā€™. When entering a book using this unified form, I would expect to be able to enter that book in only one languageā€”a translation is basically another book (different work(s), with translators, possible other different attributes in the future like creation date, etc.).

Instead, I suggest setting the ā€˜languageā€™ earlier in the form, and using that when creating the works and editions entities.

You could also ask if the book is a translation and change a few things accordingly (add translator(s), change language name, link to original work, etc.)

The backend code to generate new author and publisher will be same except:
ā€¢ No new name, sort-name, language, alias, identifier, disambiguation.
ā€¢ It will only consist of additional information if we compare it to present forms.

The backend code cannot be the same, as currently we can only create or edit one entity at a time. Some of the code can be reused, but I think you should have a better understanding of what goes on in the background, otherwise you would be in for a nasty surprise working on this project

Why did you remove sort-name, language, alias, identifier, disambiguation for these entities?
Looking at the workflow, Iā€™m not sure I understand why Alias, Identifiers and Disambiguation are at the bottom there, or what entity they refer to.
Users should have the ability to add disambiguation, aliases and identifiers for each of the entities that will be created.

Testing: [ā€¦]

You donā€™t actually mention testing, and it is crucial to ensure that the mechanism doesnā€™t break in the future when somebody else changes the code.

I am free all summer except for about last 20 days. My college resumes in August. In that time also I will be able to give 3-4 hours a day easily. [ā€¦] I plan to give 30-35 hours a week in the project

Assuming a 5 day work week, you would need to work 5-6 hours a day to reach your goal of 30-35 h/week.
Or did I misunderstand and the 3-4h days are during August only?
Itā€™s going to be a big bite to chew if you donā€™t have the whole GSOC period to work on it.

Good luck for the continuation !

1 Like

Hi! @mr_monkey

Indeed! I have tasted, the bookbrainz environment. I asure you, that I will prove to be an asset for your Institution.

I see no mention of Redux, for example, which is used to manage state in the entity editor

I know that i lack that skill in present, but i recently learned React and i am planning to learn Redux before community bonding period begins.

scope of the project seems too big considering you wonā€™t be available for the last three weeks and your level of experience of the codebase.

Due to coronavirus, the schedules of colleges is not clear for the future . But there will be no availability issue from my side. Also i will be available for 3-4 hrs during last three weeks if my college schedule is not changed. And for my level of experience, i will boost it before and during comunity bonding period (this gives my whole two months to work), and after that, when the coding period begins, we can work on creating the form :slightly_smiling_face:

There is no indication on the mockups of where in the process the user is, or how they can go back to previous sections.

I also think a summary page before submission would be a good idea.

I will surely add these soon, and update you.

This component is only used for displaying entity details, not for editing them.

I am sorry. I misunderstood. src/server/helpers/diffFormatters/entity.js is used for editing or creating.

we ultimately want to keep the existing entity-editor pages, which components will you be able to reuse, and how?

Like the existing code for aliases, identifier and disambiguation under enity-editor pages can be reused in proposed forms for creating new ones also. We will not be using modals but some of the front end code along with the functions and actions.js can surely be reused (like we will also be needing a function like onClose to be executed when we press CLOSE button.)

The validators you pasted are there, as their name suggest, to validate the input data. It is not used to determine if an entity of the same name already exists.

My bad :neutral_face:. You are right, checkIfNameExists from actions.js under name section will be used for determining if the entity already exists or not. I now understand how it is being used in entity editor.
We found the following&nbsp; {_.startCase(entityType)}{exactMatches.length > 1 ? 's' : ''} with exactly the same name or alias:

it departs from the existing guidelines (Editions have the ā€œtitle of the bookā€ as their name).

It might have slipped out of my mind. I will take care while updating the proposal.

I donā€™t understand this statement. Could you please rephrase it?

I mean, there is not much difference in creating a new book and creating a new edtion.
For both of them, we will be adding a name, publisher, release-date, physical data, edition-format and, on create pages of both of them, tere will be an an option to create a new edition too. The changes will be only that we cannot add a language for an edition. So, in that sense, creating page includes mostly same features for creating book.

a translation is basically another book (different work(s), with translators, possible other different attributes in the future like creation date, etc.).

Ok, we can go with this. We can ask the user if the book is a translation or original, and if the former is selected then add the field for the adding the original work.

Why did you remove sort-name, language, alias, identifier, disambiguation for these entities?
Looking at the workflow, Iā€™m not sure I understand why Alias, Identifiers and Disambiguation are at the bottom there, or what entity they refer to.

I am sorry, sort-name, language, alias, identifier, or disambiguation nothing will be removed for author and publisher.
I will add the necessary to mockups.
Also i mention below the page for adding alias, identifier and disambiguation that this page will be added for creating every entity

Yes, you misunderstood i will be able to give 3-4h per-day only during last 10-15 days in august, otherwise i will be well dedicated to my project.

Itā€™s going to be a big bite to chew

I am ready to take that big bite.

The challenges that i think, that will be coming my way and how i plan to increase my skill set:
In april first 10 days i am going learn REDUX and see how to use it with REACT( i learnt react in feb only so it is fresh in my mind).
In the next half of april in adding with the half month of may i will learn the codebase in depth and ask doubts.
We can do the discussion about mockups and front end during other half of april and when the coding period begins, we can continue according to the timeline.

I will be updating the timeline along with the necessary updates in 2-3 hours.
Thank you, for the generous feedback.

1 Like

I know that i lack that skill in present, but i recently learned React and i am planning to learn Redux before community bonding period begins. [ā€¦] And for my level of experience, i will boost it before and during comunity bonding period (this gives my whole two months to work), and after that, when the coding period begins, we can work on creating the form :slightly_smiling_face:

Honestly, I do not doubt your competence or your capacity to learn! Youā€™ve been slowly getting to know the project, which is a good omen.
However, please understand that the application review process starts tomorrow, and I will have to judge your capacity to lead this project to completion based on the concrete information I have available.
I wish you had time to join the project earlier and get to know it better; BookBrainz is in dire need of competent UX &UI designers :slight_smile:

Due to coronavirus, the schedules of colleges is not clear for the future . But there will be no availability issue from my side. Also i will be available for 3-4 hrs during last three weeks if my college schedule is not changed.

I understand the situation is complicated and completely in the air, and certainly do not hold it against you. However I do see an availability issue here, gaging the scope of the project and the time available.

I am sorry. I misunderstood. src/server/helpers/diffFormatters/entity.js is used for editing or creating.

Thatā€™s used to display the differences between two revisions, like on /revision/1234 page.
All the code used for creating/editing entities (on the front-end at least) in in src/client/entity-editor/.

Like the existing code for aliases, identifier and disambiguation under enity-editor pages can be reused in proposed forms for creating new ones also. We will not be using modals but some of the front end code along with the functions and actions.js can surely be reused (like we will also be needing a function like onClose to be executed when we press CLOSE button.)

That sounds sane. What do you mean by ā€œwe will also be needing a function like onClose to be executed when we press CLOSE buttonā€? Which close button exactly if weā€™re not using modals?

Also i mention below the page for adding alias, identifier and disambiguation that this page will be added for creating every entity

this page will be added for creating every entity [ā€¦] This page will be on user screen everytime a user wants to enter a new book, author or publisher or edits the same.

You didnā€™t mention the Work, Edition or Edition Group, hence my confusion. Although honestly, in a simple case with a single work, these three entities can share most of these attributes (the name and sort name should be the same for all three, while disambiguation should probably be separate for each entity.

Yes, you misunderstood i will be able to give 3-4h per-day only during last 10-15 days in august, otherwise i will be well dedicated to my project.

I see. Generally, I consider a participantā€™s studies and work to take priority over GSOC, and I do not want the project to interfere with that, but itā€™s something we could fine-tune or find a sane way to arrange.

1 Like

Hi! @mr_monkey
I also think that my skill set is definitely lacking practice and some frameworks, which can lead to lack in understanding the codebase, which can result in, me not qualifying this project in the end. This will also be coupled with the lack time. Also, as you said, you will be needing a concrete work done by me to accept my project.
I certainly want to work on my skills too, so i have decided that i will submit my proposal next year, and till then bond with this community more, get thorough with the codebase, solve more issues and get ready for next time.
Thanks a lot :slightly_smiling_face:, for helping me setting up the project in my localhost, and reviewing my application.

3 Likes

I think your proposal has nothing to be ashamed of, and I encourage you to submit it!
The proposal itself is good practice, and a good exercise. I think going all the way to the end of the process is an achievement in itself and valuable experience.

I wanted to be upfront about my perspective (I think it can be useful feedback), with no intention to talk you out of completing your proposal !
And to clarify agin, I do not doubt your capacity to learn the frameworks, rather my worry is about the time available during the GSOC period. I know from personal experience the codebase is more complicated than it seems, and getting used to it takes a long while.

The deadline to submit on the GSOC website is in a few hours, good continuation :slight_smile:

3 Likes

I understand your concern, and no doubt i have come a long way from when i started to set my localhost. It was indeed, a big learning experience. Your feedbacks were truly useful.
Actually, i am still getting used to react (which i started to learn, after getting a look at bookbrainz codebase, around february) then it took me long to get the setup on my PC, then my exams came for around one week, then after first week of march i actually dived intoā€¦
so it will take me a more time to get comfortable.
Thanks again for the support !

1 Like

Hey @Prabhleen, Shouldnā€™t you at-least submit the proposal ? :slight_smile:. Its great to have just submitting a proposal as a good achievement. Its great to see students participate. Truthfully this is my third time applying for Summer of Code. You can get comfortable with the code during the assessment period and the community bonding period.

Great work so far :+1:

2 Likes