Skip to content

Report

Jump to bottom
Tommy edited this page Feb 28, 2020 · 99 revisions

Report for assignment 4

  1. Project
  2. Onboarding experience
  3. Selected issue(s)
    1. Integrate ShortScience #6015
      1. Requirements affected by functionality being refactored
      2. Existing test cases relating to refactored code
      3. Test results
      4. Patch/fix
      5. UML Class Diagram
    2. Integrate BibSonomy #5888
      1. Requirements affected by functionality being refactored
      2. Existing test cases relating to refactored code
        1. Frontend
        2. Backend
      3. Test results
      4. Patch/fix
      5. Work plan
    3. Keyboard shortcuts for data entry/editing #6017
      1. Requirements affected by functionality being refactored
      2. Existing test cases relating to refactored code
      3. Test results
      4. Patch/fix
      5. UML Class Diagram
        1. Before implementation:
        2. After implementation:
  4. Effort spent
    1. David
    2. Felix
    3. Kristoffer
    4. Meng-Jin
    5. Tommy
  5. Overall experience
    1. Tommy
    2. Felix
    3. Kristoffer
    4. David
    5. Meng-Jin

Project

Name: Jabref

URL: https://github.com/JabRef/jabref

JabRef is an open-source, cross-platform citation and reference management tool.

Onboarding experience

Did it build and run as documented?

  • Yes.

See the assignment for details; if everything works out of the box, there is no need to write much here. If the first project(s) you picked ended up being unsuitable, you can describe the "onboarding experience" for each project, along with reason(s) why you changed to a different one.

Did you have to install a lot of additional tools to build the software?

  • No, the project used a gradle wrapper which took care of the different dependencies. The only thing we had to supply on our own was Java 13.

Did the build conclude automatically without errors?

  • The build passed without errors.

How well do examples and tests run on your system(s)?

  • All tests concluded without errors on Linux and Windows, while one single test failed on mac.

We also investigated a number of other projects, where the main contestors to Jabref was Zulip and Youtube-dl. Zulip was discarded, since it was not possible to run locally, while Youtube-dl was deemed a bit too unstructured in it's dealings with issues (a lot of them were requests from users).

Selected issue(s)

Integrate ShortScience #6015

Title: Integrate ShortScience #6015

URL: https://github.com/JabRef/jabref/issues/6015

Summary in one or two sentences

  • To integrate ShortScience which is a web page that provides user written summaries of papers.

Requirements affected by functionality being refactored

  • 6015FR1 Search ShortScience from JabRef: There should be an easy way to query ShortScience based on the article title from within JabRef.
  • 6015FR2 Special character support: The ShortScience querying functionality should support reserved special URL characters as defined by RFC3986.

Optional (point 3): trace tests to requirements.

  • 6015FR1 is tested through getShortScienceSearchURLLinksToSearchResults and getShortScienceSearchURLReturnsEmptyOnMissingTitle.
  • 6015FR2 is tested through getShortScienceSearchURLEncodesSpecialCharacters.

Existing test cases relating to refactored code

No existing tests relate to the functionality being added.

Test results

Before on Windows and after on Windows](), before on Mac and after on Mac.

New tests pass, and the unrelated failing test on MacOS still fails.

New tests

Patch/fix

The solution consists of a new class, OpenShortScienceAction, and some integration in various methods. UML Diagram

Diff is easiest viewed on GitHub

PR is open and accepted towards JabRef

UML Class Diagram

This change does not contain a refactor, as it is exclusively new code.

UML-shortScience

SimpleCommand is a preexisting class that forms the base class of all Action classes in the project, which are interactable GUI elements. The SearchShortScienceAction is a new such Action which, when executed, opens the user's web browser to the search page of ShortScience. In order to generate the URL that is open, it depends on the ExternalLinkCreator class which is part of the logic package and tested by ExternalLinkCreatorTest.

In addition to the changes in the UML diagram, the new action was added to the enum of existing actions StandardActions and to the list of items in the context menu returned by gui.maintable.RightClickMenu.create.

Integrate BibSonomy #5888

Title: Integrate BibSonomy #5888

URL: https://github.com/JabRef/jabref/issues/5888

Summary in one or two sentences

  • To integrate BibSonomy.org which is a tool to collect bibliographic information. This functionality was implemented via a no longer supported plugin in a previous version of JabRef (since version 2.12, plugin support was removed), which could be ported into the new UI framework used by JabRef, JavaFX.

Requirements affected by functionality being refactored

  • 5888FR1 BibSonomy Settings: The user should be able to customize the BibSonomy features.

    • 5888FR1.1 Set BibSonomy credentials: The user should be able to user their own credentials
      • 5888FR1.1.1 Set username
      • 5888FR1.1.2 Set API key
    • 5888FR1.2 Set preferences for Tag Cloud:
      • 5888FR1.2.1 Tag Cloud size: The user should be able to set the number of tags shown inside the Tag Cloud.
      • 5888FR1.2.2 Tag Cloud ordering: The user should be able to set the ordering of the tags inside the Tag Cloud.
        • 5888FR1.2.2.1 Frequency: The user should be able to order tags by frequency of use.
        • 5888FR1.2.2.2 Alphabetical: The user should be able to order tags alphabetically.
        • 5888FR1.2.2.3 Folkrank: The user should be able to order tags according to their Folkrank.
        • 5888FR1.2.2.4 Date: The user should be able to order tags according to their date.
    • 5888FR1.3 Set preferences Fetching new BibSonomy entries: The user should be able to customize options for how the fetching of new entries is handled.
      • 5888FR1.3.1 Fetch size: The user should be able to set the number of posts to fetch per request.
      • 5888FR1.3.1 Pagination: The user should be able to set if they should be warned if more posts are available.
      • 5888FR1.3.2 Missing tags: The user should be able to set if they should be warned if posts are missing tags.
      • 5888FR1.3.3 Updates: The user should be able to set whether the tags should be updated on startup.
      • 5888FR1.3.4 Upload: The user should be able to set whether documents should be uploaded on export.
      • 5888FR1.3.5 Download: The user should be able to set whether documents should be downloaded on import.
    • 5888FR1.4 Set default visibility: The user should be able to set their default visibility.
      • 5888FR1.4.1 Private: Entries are only available to the user
      • 5888FR1.4.2 Public: Entries are available to all users
    • 5888FR1.5 Extra fields: The user should be able to set which BibTex fields should be visible on the Extra tab of the entry editor

  • 5888FR2 Fetch new entries from BibSonomy: The user should be able to fetch new bibliographic entries from BibSonomy.

    • 5888FR2.1 Fetch new entries via Full Text Search: The user should be able to fetch new bibliographic entries via Full Text Search.
    • 5888FR2.2 Fetch new entries via Tag Search: The user should be able to fetch new bibliographic entries via Tag Search.
    • 5888FR2.3 Fetch new entries via the BibSonomy Tag Cloud: The user should be able to fetch new bibliographic entries via the Tag Cloud from BibSonomy.
      • 5888FR2.3.1 Set source of Tag Cloud: The user should be able to specify the source of the tags, i.e. tags from the user, a group the user is a part of or all users.

  • 5888FR3 Present new entries: The user should be presented with the found entries in some manner.

    • 5888FR3.1 Select new entries: The user should be able to select entries to import.
    • 5888FR3.2 Deselect new entries: The user should be able to deselect entries, i.e. discarding them from the list of entries to import, but still leaving the option to select again.
    • 5888FR3.3 Deselect duplicate entries: The user should be able to deselect duplicate entries.
    • 5888FR3.4 Delete new entries: The user should be able to remove entries from the list of possible entries to import, without leaving the option to select again.
    • 5888FR3.5 Generate BibTeX key: The user should be able easily generate a BibTeX key for the new entries.
    • 5888FR3.6 Import new entries: The user should be able to import selected entries.
    • 5888FR3.7 Cancel import: The user should be able to abort the importing of the new entries.

  • 5888FR4 Export entries to BibSonomy: The user should be able to export their collection to BibSonomy.

  • 5888FR5 Delete entries from BibSonomy publication collection: The user should be able to remove entries from their personal collection on BibSonomy.

  • 5888FR6 Synchronize local and remote BibSonomy publication collection: The user should be able to synchronize their local and remote BibTeX entries.

    • 5888FR6.1 Solve synchronize conflicts: The user should be able to solve conflicts between local and remote BibTeX entries.

  • 5888FR7 Download documents: The user should be able to download their documents BibTeX entries.

  • 5888FR8 Proxy settings: The user should be able to access BibSonomy features via a proxy.

Existing test cases relating to refactored code

Frontend

There are no existing test cases relating to refactored code since this is new functionality.

Backend

According to the JabRef team, the old plugin should still be able to handle the backend. Looking though the source code for the plugin, it seems that it is currently lacking tests as well.

Test results

Since this task will not be completed due to time restrictions, no changes to the source code has been made at this stage, and therefore this section is not applicable.

Patch/fix

Since this task will not be completed due to time restrictions, no changes to the source code has been made at this stage, and therefore this section is not applicable.

Work plan

The plan for this issue was the following:

  1. Identifying the requirements of the BibSonomy features, based on the old plugin.
  • This was completed, and the list of requirements can be found above in a list format, or in a text format here.
  1. Make UI mockups for the new functionality, based on the previously identified requirements.
  • This was completed, and the mockups can be found here.
  1. Present the mockups to the JabRef team, and gather feedback from them.
  • This was completed, and their comments can be found here
  1. Continue on the work introduced in #2157 by cherry-picking the first commit of the pull request.
  2. Design project architecture and testing strategy.
  • Try to connect with existing frameworks, for example fetching new entries from BibSonomy should probably be tested in a similar manner to the tests performed on the same functionality for Google Scholar and CiteSeerX.
  1. Implement each of the UI-elements
  • Settings #11
  • Direct Search #12
  • Tag Cloud #13
  • Filtering through new entries #14
  • Export and Delete #15
  • Synchronize and Download#16
  • Synchronize Conflict Resolution #17
    • There is no need for an explicit UI-element for this, since this functionality is already implemented, and just needs to be called.
  • Proxy Settings #18
    • There is no need for an explicit UI-element for this either, as this functionality is already implemented on a application level via Options → Preferences → Advanced → Network for JabRef. However, there might be a need to look over how this global setting can be utilized by BibSonomy features.
  • Test-credentials #20
  1. Write a user documentation for the BibSonomy features #21

The points 1-3 has been completed, while the others are left untouched for the scope of this assignment. It is quite hard to estimate the time needed to complete this assignment, since the work done so far has been code independent. However, since the backend logic in large part seems to be implemented, and a lot of the GUI elements needed could be largely influenced by already existing implementations, the task might not be as big as it may seem. A rough estimate would be around 20-30 hours, documentation for the report included.

Keyboard shortcuts for data entry/editing #6017

Title: Keyboard shortcuts for data entry/editing #6017

URL: https://github.com/JabRef/jabref/issues/6017

Summary in one or two sentences

  • Add Emacs keyboard shortcuts when editing data in the program. This was implemented in previous versions 3.X.X but was removed in the project refactoring.

Requirements affected by functionality being refactored

  • 6017FR01 Toggle the use of Emacs key bindings: The functionality to use the Emacs key bindings should be able to be toggled on and off.

  • 6017FR02 Toggle the use of conflicting Emacs key bindings: The functionality to use Emacs key bindings that conflict with standard shortcuts, should be able to be toggled on and off.

  • 6017FR03 Ctrl + F (move cursor right one step): Pressing the key combination Ctrl + F should move the cursor one step to the right when in a text-field.

  • 6017FR04 Ctrl + B (move cursor left one step): Pressing the key combination Ctrl + B should move the cursor one step to the left when in a text-field.

  • 6017FR05 Ctrl + D (delete character at cursor): Pressing the key combination Ctrl + D should remove the character to the right of the cursor when in a text-field.

  • 6017FR06 Ctrl + A (move cursor to the beginning of the line): Pressing the key combination Ctrl + A should move the cursor to the beginning of the line when in a text-field.

  • 6017FR07 Alt + < (move cursor to the beginning of the document): Pressing the key combination Alt + < should move the cursor to the beginning of the text-field.

  • 6017FR08 Alt + Shift + < (move cursor to the end of the document): Pressing the key combination Alt + Shift + < should move the cursor to the end of the text-field.

  • 6017FR09 Ctrl + P (move cursor up one line): Pressing the key combination Ctrl + P should move the cursor up one line when in a text-field.

  • 6017FR10 Ctrl + N (move cursor down one line): Pressing the key combination Ctrl + N should move the cursor down one line when in a text-field.

  • 6017FR11 Alt + L (lowercase word to the right of the cursor): Pressing the key combination Alt + L should lowercase the word right to the cursor in a text-field.

  • 6017FR12 Alt + U (uppercase word to the right of the cursor): Pressing the key combination Alt + U should uppercase the word right to the cursor in a text-field.

  • 6017FR13 Alt + C (capitalize word to the right of the cursor): Pressing the key combination Alt + C should capitalize the word right to the cursor in a text-field.

  • 6017FR14 Ctrl + K (remove line): Pressing the key combination Ctrl + K should remove all the characters to the right of the cursor on a line in a text-field.

  • 6017FR15 Alt + D (remove word to the right of the cursor): Pressing the key combination Alt + D should remove the word to the right of the cursor's current position in a text-field. If the cursor is in a word, the characters to the right of the cursor in the aformetioned word should be removed.

  • 6017FR16 Alt + DELETE (remove word to the left of the cursor): Pressing the key combination Alt + DELETE should remove the word to the left of the cursor's current position in a text-field. If the cursor is in a word, the characters to the left of the cursor in the aformetioned word should be removed.

Optional (point 3): trace tests to requirements.

  • 6017FR11 is tested through lowercaseEditsTheNextWord.
  • 6017FR12 is tested through uppercasePreservesSpace, uppercasePreservesNewlines, uppercasePreservesTab, uppercasePreservesDoubleSpace, uppercaseIgnoresTrailingWhitespace and uppercasePreservesMixedSpaceNewLineTab.
  • 6017FR13 is tested through capitalizePreservesNewlines.
  • 6017FR15 is tested through killWordTrimsTrailingWhitespace, killWordRemovesFromPositionUpToNextWord and killWordRemovesNextWordIfPositionIsInSpace.
  • 6017FR16 is tested through backwardsKillWordTrimsPreceedingWhitespace.

Existing test cases relating to refactored code

There are no existing test cases relating to refactored code since this is new functionality.

Test results

Before on Windows
Before on Mac

After on Windows
After on Mac

12 new tests have been added

All new tests pass. They test for behavior edge cases in for the emacs comand. Such as right resulting text string and the position of the caret.

New tests

Patch/fix

The diff is easiest viewed on GitHub.

Optional (point 4): the patch is clean.

Optional (point 5): passes automated checks

UML Class Diagram

Before implementation:

before_implementation

This represents the GUI preference settings. That hasn't yet gotten the connections to regulate the key bindings.

EnrtyEditor GUI class that allows editing of a bib entry.

KeyBindning is a enum class for the diffrent key bindings.

EnrtyEditorTabView is a class that defines the view of a tab of the Entry editor view.

EntryEditorTabViewModel is a class that provides the data for the Entry editor tab.

JabRefGUI is the main GUI view/windows for the JabRef program.

JabPrefPrefrences holds all the preference settings data.

After implementation:

after_implementation The changes in the class structure are that three new classes have been added. StringChangeNextWord which is a class manipulating words in Strings. A test class for said class, and the class EmacsKeyBindings which contains the logic for the keybindings.

There is now a dependency between EmacsKeyBindings and JabRefPreferences in order to know whether or not to enable the key bindings. As well as one between StringChangeNextWord since it contains all the logic for manipulating Strings in the way that the key bindings require.

JabRefGUI creates a dependency to EmacsKeyBindings since JabRefGUI contains the event listener required to capture key press events which can then be passed on to EmacsKeybindings.

Effort spent

David

For each team member, how much time was spent in

  1. plenary discussions/meetings: 2 hours

  2. discussions within parts of the group: 2.5 hours

  3. reading documentation: 5 hours

  4. configuration and setup: 0.5 hours

  5. analyzing code/output: 3 hours

  6. writing documentation: 6.5 hours

  7. writing code: 10 hours

  8. running code: essentially 0 hours

For setting up tools and libraries (step 4), enumerate all dependencies you took care of and where you spent your time, if that time exceeds 30 minutes.

What took time was setting up the project's IntelliJ configuration, including a Java 13 SDK. This was relatively painless, but had to be done on two computers using different operating systems.

Felix

For each team member, how much time was spent in

  1. plenary discussions/meetings: 2h

  2. discussions within parts of the group;

  • Of course there was some discussions between me and other members, these hours are baked into the other tasks

  1. reading documentation: 2,5h

  2. configuration and setup;

  3. analyzing code/output: 4h

  4. writing documentation: 16h

  5. writing code;

  • Creating the GUI mockups involved some coding, but since the task was more heavy in the documentation department, I won't overlap time spent here.
  1. running code: 1,5h

For setting up tools and libraries (step 4), enumerate all dependencies you took care of and where you spent your time, if that time exceeds 30 minutes.

Kristoffer

For each team member, how much time was spent in

  1. plenary discussions/meetings: 2 hrs

  2. discussions within parts of the group: 1 hrs

  3. reading documentation: 8 hrs

  4. configuration and setup: IntelliJ 1.5 hrs

  5. analyzing code/output: 0.5 hrs

  6. writing documentation: 10 hrs

  7. writing code: 5 hrs

  8. running code: insignificant

Meng-Jin

For each team member, how much time was spent in

  1. plenary discussions/meetings: 3 hours

  2. discussions within parts of the group: 1 hours

  3. reading documentation: 5 hours

  4. configuration and setup: 1 hours

  5. analyzing code/output: 6 hours

  6. writing documentation: 1 hours

  7. writing code: 8 hours

  8. running code: 1 hours

For setting up tools and libraries (step 4), enumerate all dependencies you took care of and where you spent your time, if that time exceeds 30 minutes.

Tommy

For each team member, how much time was spent in

  1. plenary discussions/meetings;

    • 2h

  2. discussions within parts of the group;

  3. reading documentation;

    • 2h

  4. configuration and setup;

  5. analyzing code/output;

    • 9h

  6. writing documentation;

    • 5h

  7. writing code;

    • 8h

  8. running code?

For setting up tools and libraries (step 4), enumerate all dependencies you took care of and where you spent your time, if that time exceeds 30 minutes.

Overall experience

What are your main take-aways from this project? What did you learn?

Tommy

I think it was really fun and a learning experience. Maybe our team was lucky in picking a good project where the owner were super friendly. I have learned among other thing that it is easy to underestimate how much work a feature might need. Also how important a good structure and documentation is for jumping in to bigger projects.

Felix

Personally I have to say that this assignment was quite fun and valuable as well. Since coding took a backseat in my work, and I instead focused on the more documentation heavy side of the SE process, I do feel that I have learnt a lot about a subject which might be at the forefront of every aspiring developers mind. One of the key lessons I will take away from this is that the time required to actually take ideas that are so clear in your mind, and actually put them to paper (or some other form of deliverable), shouldn't be underestimated. Also, I think it was quite fun how excited, and accommodating the owners of the project where, giving us feedback along the way!

Kristoffer

This was the most enjoyable lab out of the ones in this course. I really liked actually contributing with something meaningful for a program that people actually use. The main takeaway will probably be how much time is actually spent reading documentation and wrapping your head around big code bases. And the fact that with enough time spent, it's actually possible to get a grip huge amounts of code.

David

I think my main take-away from this project is that open source projects don't have to be scary. Previously I have been a little bit intimidated of the sheer scope of open source software, and felt slightly inadequate. Through this lab and the conversations I've had with the maintainers of the project I've come to realize that everyone has the abilities to help with something in OSS, whether it be documentation or code, and that the people running the projects don't have to be draconian in their reviews.

I learned the importance of documentation and examining what already exists in a project before writing your own code. This is critical in order to avoid unnecessary duplicate implementations that become huge sources of bugs.

Meng-Jin

This is my first time to look into the actual issues in the open source project, which stimulate me to research for the libraries, functions, documentations that I have not digged into before. Besides, by doing this project, I learned that the practical issues are totally different from theoretical ones. To improve my software engineering skills, it is necessary to participate in open source development to gain more experiences of handling real-world problems. I really learned a lot in this project!

Clone this wiki locally