[REVIEW]: DoSOCS: A System for Managing Open Source Risk about joss-reviews HOT 35 CLOSED

👋 @mlinksva - are you still in the process of completing this review?

from joss-reviews.

Thanks for submitting this @germonprez! It looks like this submission is missing the JOSS paper (paper.md). Could you take a look at our submission guidelines on how to structure the paper and let me know when you've added it to your repo?

from joss-reviews.

🎏 flagging this as stale 🎏

If there's no update here by @germonprez in the next month I'll assume they want this paper withdrawn.

from joss-reviews.

@arfon I've uploaded the paper.md paper.bib, and codemeta.json in the paper folder:

https://github.com/DoSOCSv2/DoSOCSv2/tree/master/paper

Happy to make changes as needed. Thanks!

from joss-reviews.

✋ I'll review this, thanks for ping @arfon.

I haven't investigated whether the bot only responds to certain users, but I'll try anyway:

@whedon assign @mlinksva as reviewer

from joss-reviews.

@whedon commands

from joss-reviews.

Here are some things you can ask me to do:

# List all of Whedon's capabilities
@whedon commands

# Assign a GitHub user as the reviewer of this submission
@whedon assign @username as reviewer

# List the GitHub usernames of the JOSS editors
@whedon list editors

# List of JOSS reviewers together with programming language preferences and domain expertise
@whedon list reviewers

# Change editorial assignment
@whedon assign @username as editor

# Set the software archive DOI at the top of the issue e.g.
@whedon set 10.0000/zenodo.00000 as archive

# Open the review issue
@whedon start review

🚧 Important 🚧

This is all quite new. Please make sure you check the top of the issue after running a @whedon command (you might also need to refresh the page to see the issue update).

from joss-reviews.

✋ I'll review this, thanks for ping @arfon.

Wonderful, many thanks @mlinksva.

I haven't investigated whether the bot only responds to certain users, but I'll try anyway:

Nice try @mlinksva. @whedon should have given you an error but it looks like he failed silently.

from joss-reviews.

@whedon assign @mlinksva as reviewer

from joss-reviews.

OK, the reviewer is @mlinksva

from joss-reviews.

@mlinksva - you should just be able to update the checklist on this issue as you proceed with your review.

UPDATE: I've also just added the paper PDF to the top issue.

from joss-reviews.

Version: Does the release version given match the GitHub release (v2.0)?

I'm not sure. It seems that "v2" here is not really a software version, but part of the name of the software, indicating that there was a previous implementation -- the v2 suffix plays the same role a neo prefix would. The current version seems to be 0.16.1. Also the README says "dosocs2 is under heavy development; expect frequent backwards-incompatible changes until a 1.x.x release!"

@germonprez should the version submitted be 0.16.1?

from joss-reviews.

Yes, mistake on my end. The v2 in the name is the reboot of DoSOCS. We had an original version v1 that was really proof of concept. The v2 is the second iteration on DoSOCS -- a fundamental rewrite.

You read this correctly.

from joss-reviews.

Not really pertinent to review, but for my future reference, example of an Apache-2.0->GPL-3.0+ license change with rationale: DoSOCSv2/DoSOCSv2@8704053#diff-9879d6db96fd29134fc802214163b95a

from joss-reviews.

Great, I changed the version field above to 0.16.1.

from joss-reviews.

Quick comments on the paper before I get to the software itself.

A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?

Could be stronger. States what software does from which problem can be inferred, target audience is "in an organization" with those problems. Skimming the first page of accepted papers at http://joss.theoj.org/papers/popular it seems most provide a bit more detail on the problem/need addressed and/or how submitted software relates to other software.

Also, the paper includes a reference to the software the paper is about. It doesn't look like any accepted papers have this.

from joss-reviews.

Under documentation:

Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

https://github.com/DoSOCSv2/DoSOCSv2/blob/62f48ffbea96e7befe113ea0298691d2ccfdc96c/CONTRIBUTING.md says "The contribution rules for DoSOCS are currently being rewritten. You are welcome to create issues, but we can't accept pull requests from the community at this time." I suppose this technically does all of 1-3 if "can't accept" works for 1 and "welcome to create issues" also implies this is how to seek support. @arfon I could use some guidance on whether this is satisfactory for checking off community guidelines.

from joss-reviews.

@arfon I could use some guidance on whether this is satisfactory for checking off community guidelines.

This isn't great but I think it does meet the requirements for 1--3.

from joss-reviews.

Changes to the statement of need have been merged

from joss-reviews.

Great, I see in DoSOCSv2/DoSOCSv2#94

I don't know how the paper PDF is generated, but I've gone ahead and checked off the relevant items.

from joss-reviews.

Remaining checklist items.

Functionality: Have the functional claims of the software been confirmed?

README claims:

dosocs2 is a command-line tool for managing SPDX 2.0 documents and data. It can scan source code distributions to produce SPDX information, store that information in a relational database, and extract it in a plain-text format on request.

The discovery and presention of software package license information is a complex problem facing organizations that rely on open source software within their innovation streams. dosocs2 enables easy creation of a "bill of materials" for any software package to represent associated license information. In addition, dosocs2 and can be used in the creation and continuous maintenance of an inventory of all open-source software used in an organization.

Scanning/storing/extracting it can plainly do (though one has to remember/guess/look in database without help from dosocs2 for integer package id in order to do the last, unless I'm missing something).

I'm not sure about easy creation of a bill of materials, unless raw SPDX documents are taken to be a bill of materials. I suspect this may just be a documentation issue: state that SPDX documents are intended to serve as BOM, or the easy part is that the info is in a database that one can query with SQL to generate whatever BOM or other report one wants. An end-to-end example of scanning, BOM generation, and continuous maintenance would be really helpful. Perhaps the dosocs2 itself could be the subject of the end-to-end example.

It would also be helpful to document how an organization would use dosocs2 in relation to other tools, or not. dosocs2 includes a component from fossology. Would an organization using fossology have any reason to also use dosocs2? How?

Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).

See above.

Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g. API method documentation)?

--help outputs acceptable manpage style documentation.

/doc contains some useful info on what the available scanners do.

If user needs to query database for reporting (see above), would be nice to have that schema documented.

Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?

It does have tests in tests which are run by CI. Don't know how comprehensive. Ideally running and adding tests might be documented in CONTRIUBTING.md. I'm going to guess that what's already there is satisfactory for this review checkoff.

from joss-reviews.

Updates have been made and merged to the README.

1. removed the 'easy BOM' statement and just declared that it produces an SPDX document
2. included a DFD to represent a potential organizational use of dosocs2. It is quite possible that a company would use FOSSology and dosocs2. FOSSology is really a 1-off check of a software package. Dosocs2 is built with the intention of coordinating discovery as part of a larger organizational workflow.

I didn't really understand the suggestion: Perhaps the dosocs2 itself could be the subject of the end-to-end example.

from joss-reviews.

Thanks. Suggestion was showing how dosocs2 could "be used in the creation and continuous maintenance of an inventory of all open-source software used in" itself.

In any case I'm fine with checking off the remaining items now. Not having done a review here before, @arfon can I get a second opinion?

from joss-reviews.

Oh, one other thing, the title "DoSOCS: A System for Managing Open Source Risk" seems an exaggeration -- the DFD shows it is a tool that could be part of a system for managing open source risk. Also missing "v2". "DoSOCSv2: A System for SPDX 2.0 Document Creation and Storage" would seem more accurate to me.

Finally, just out of curiosity, what does DoSOCS stand for/expand to? Just realized I don't know.

from joss-reviews.

Ok. These are fixed and being merged.

Regarding the name:

It used to be called DoSPDX when it was first a contribution to the Yocto project
We moved off the SPDX for a few reasons
We then went to SOCS (simple open compliance system) and kept the Do part

the v2 part is because it was a full rewrite of an earlier version of DoSOCS that had many technical problems. It just sort of stuck from that point!

from joss-reviews.

Thanks @germonprez. Not important for this review, but I'd suggest adding that background trivia the project's README#History ... makes the project a bit more approachable IMO.

from joss-reviews.

Can do!

from joss-reviews.

In any case I'm fine with checking off the remaining items now. Not having done a review here before, @arfon can I get a second opinion?

@mlinksva - yep, I think this is looking good. Thanks for checking (and reviewing 😄 )

from joss-reviews.

@arfon all checkboxes are checked. If there's anything else I need to do, just let me know.

from joss-reviews.

@arfon all checkboxes are checked. If there's anything else I need to do, just let me know.

👍 thanks @mlinksva.

@germonprez - At this point could you make an archive of the reviewed software in Zenodo/figshare/other service and update this thread with the DOI of the archive? I can then move forward with accepting the submission.

from joss-reviews.

Thanks @arfon and @mlinksva 😃

@arfon does this work: https://dx.doi.org/10.6084/m9.figshare.4239665.v1

from joss-reviews.

@mlinksva many thanks again for the thorough review.

@germonprez - your paper is now accepted. Your DOI is http://dx.doi.org/10.21105/joss.00038 🚀 🎉 💥

from joss-reviews.

@germonprez - one issue I didn't catch during the processing is that you have my ORCID listed in the paper.md (https://raw.githubusercontent.com/DoSOCSv2/DoSOCSv2/master/paper/paper.md). If the authors have an ORCIDs could you please update the paper.md file with these? If not, please update and remove my ORCID so it's not associated with you 😁

from joss-reviews.

done!

from joss-reviews.

done!

Thanks.

from joss-reviews.