For new contributors: package/class/activity diagrams

I am looking to create package/class/activity diagrams for the project source code (to simplify contributor onboarding), but hope to get some guidance with what exactly would be needed. Any good examples of what diagrams might be useful?

1 Like

Thanks for your interest,

if you want to create a diagram I would start with a package diagram e.g. as it’s described here
You can look at https://github.com/JabRef/jabref/wiki/High-Level-Documentation

Regarding Activity Diagrams, I think it would be cool to see what exactly happens when you insert an entry in JabRef, e.g. which actions are triggered (from the actual insertion to other GUI related stuff and autosave etc)

We also have an outdated diagram for the groups package.

Regards

1 Like

Great, thank you for the reference!!!
Now I’m trying to create an overall package diagram(s) that would allow to understand JabRef as a whole, yet package dependency diagrams come out too complicated. Even small part of GUI looks like this:


Would you recommend a different way of looking at it? Maybe grouping packages together on some criteria? If you were to draw it on paper, what would it look like?
Thanks again!!!

Further question. The class diagrams (as the one you mentioned), which packages do you think they are useful for? Is something like this helps or just re-states the obvious…?
image

The group diagram looks indeed helpful.
Regarding the gui, here it would make indeed make sense to only display the core components, e.g. the side panel (groups and open office), the base panel with the entry editor and preview panel and the maintable and maybe the menu. The rest are details.
I imagine somethng like this:

I think the most imporant class is org.jabref.model.BibEntry and the org.jabref.model.database classes (e.g. Bibdatabase and Bibdatabasecontext) as they represent the core concepts of JabRef.
E.g. a bibdatabase (library) is the bib file as whole which has none or theoretic infinetly entries and some addtional metadata (e.g. groups information, sort order…).

And regarding the process, I think it would be useful to have an activiy diagram for inserting an entry,
e.g. you insert an entry in the gui => it’s validated and then stored in the database and a notifcation (EventBus) is triggered to inform that an entry has been inserted. Usually followed by an autosave which serializes the current db.

Hi all, I had a chance to spend more time on producing diagrams for the project. For now, just static structure (not activity). Some of the samples are below and I would be curious about your opinion on these.

Overview of whole packages for example:
org.jabref.gui.entryeditor

Or specific classes for example:
BibDatabase

Other than activity diagrams (I’ll get to them next), what do we need before we link diagrams to project documentation?

Thank you,
Alex

These look nice and should be really helpful for new contributors. Thanks for your work! We can create a new wiki page and then put the diagrams there. Or if they are semi-automatically produced we can also automate the process and then publish them to github pages?

I have re-published full set of diagrams here: https://sourcespy.com/github/jabref

They are nearly entirely automatically produced, therefore I think it would be easier if I commit to hosting them and run updates periodically to reflect current state of the code.

Would it be possible to link to the diagrams from here https://github.com/JabRef/jabref#contributing and in High-Level-Documentation in Wiki? Should I do it myself?

Also, can you suggest a best way to collect feedback about usability/need of those? Thank you!!!

The diagrams look really nice!

Yes, please edit the wiki yourself (and provide a PR with the changes). The forum or gitter is probably the right place to get feedback.