Open Subjects Call: software for teaching

Resources Open Subjects Calls
  • 06 Sep, 2022

This is an automatic translation generated by artificial intelligence. May contain errors.

[Draft: non-final document, under review]

The Recognition of Open Subjects Publication Call allows teachers to submit, in the category “Other materials,” software (computer programs) used in teaching: solved exercises, example programs, programs created to facilitate understanding of aspects of the subject, etc. This guide provides some recommendations on how to present this type of software for consideration in said call.

Characteristics

To be considered among the open-access materials submitted for the evaluation of a subject (category “Other materials”), following the principles of the call, the following characteristics should be met:

  • The software is available in a public repository, in one of the formats accepted by Software Heritage (for example, git, svn or bzr).
  • The software is used in the subject submitted to the call during the 2022-2023 academic year.
  • At least one of the teachers teaching the subject is also the author of the submitted software.
  • The software includes instructions on how to use it, or these instructions are in some other open-access material used in the subject.
  • The source code of all submitted software is included in the deposit and is properly licensed with a license recognized by OSI.

Deposit

Steps to follow to deposit software so that it can be considered in the “Other materials” category of the Recognition of Open Subjects Call:

  • Repository preparation, including a README.md file.
  • Deposit in Software Heritage.
  • Obtaining the Software Heritage identifier for the version to be submitted and a compressed file with the corresponding contents.
  • Upload to BURJC Digital (DSpace) the README.md file in PDF format, with the compressed file as an attachment, including the Software Heritage identifier and the public repository URL in the metadata.

Once this process is completed, the data of the deposited software can already be included in the call application form (see the end of this guide).

NOTE: both the deposit in Software Heritage and the obtaining of the identifier and the compressed file can be done more conveniently with the Software Heritage browser extension

These steps are detailed below.

Repository preparation

Before depositing the software, a public repository must be prepared that will later be archived and deposited:

  • If the software is already in a public repository on a software hosting service (such as GitHub or GitLab, for example), you can prepare that repository, following the instructions detailed below. If not, you will first need to upload the software to one of these services. If you don’t know how to do it, you can follow the GitHub mini-course “Uploading your project to GitHub” or the “Repository” documentation from GitLab.

  • Prepare a README.md file in Markdown format (or simply in plain text format) describing the contents of the repository, so that its teaching function can be understood and can be used by someone interested in using them to learn.

  • Prepare a LICENSE or COPYING file, with the license used, which must be one of those recognized by OSI (Open Source Initiative) as an “open source” license (see list of licenses recognized by OSI). As far as appropriate for the specific case, it is recommended to use a license from the category “popular and widely-used or with strong communities”.

  • Recommendation: mark the header of all source files with a copyright notice indicating the date and authorship, and the SPDX identifier of the license used. For example, for a Python file distributed under the GNU GPL 3.0 or later license:

__copyright__ = "Copyright (C) 2022 Name Surname"
__license__ = "GPL-3.0-or-later"
  • Recommendation: Organize the contents of the repository into directories, appropriately for its use, and include documentation or references to the software documentation.

Deposit in Software Heritage:

The deposit in Software Heritage will begin by checking if it is already deposited there (because it is very possible that it has already been done automatically), in the specific version submitted to the call. If not, the deposit will be forced:

  • If the software is already in a GitHub or GitLab repository, it is very likely that it is already archived in Software Heritage, so perhaps this step is not necessary. In any case, to ensure that it is properly archived, it is better to first update the repository and then deposit that version in Software Heritage.

  • Follow the instructions in “Save code now” to deposit the software.

Obtaining identifier and compressed file

To obtain the SWHID of the version to be submitted to the call, and a compressed file with the deposited contents:

  • Once deposited in Software Heritage, search for the repository in the Software Heritage search form. Locate the version you want in it: Click on “History” to see all archived versions (commits) in Software Heritage, and locate the one you want to submit to the call.

  • Once you have located the specific version, click “Download”. Shortly after, the download of a file with extension tar.gz will begin, which will contain all the files deposited in that version, compressed. This is the compressed file that you will need to upload to BURJC Digital. The file name will give you the SWHID: it will be the name of the file generated by Software Heritage, removing .tar.gz and replacing “_” with “:”. For example, this is an SWHID: swh:1:dir:46dfa1d1d13ae5a725c4ff53f2714f1d237fff7d.

Upload to BURJC Digital

To complete the process, you will need to upload the compressed file to BURJC Digital, the Open Archive of URJC:

  • Create a PDF file that has the same contents as the README.md (or README) file of the repository version you are going to upload. You can do this in many ways:

    • Using a conversion service, such as MARKDOWNtoPDF.

    • Copying the text into an editor and saving as PDF from it (in this case, better copy respecting the format of the HTML version provided by GitLab or GitHub).

    • From the IDE, if you have the option to save a Markdown document as PDF (you may need to install some extension).

    • Using pandoc. After installing it, run:

pandoc README.md -s  -f gfm -V colorlinks=true -o README.pdf

  • Follow the BURJC Digital instructions to perform the deposit:

    • Choose the collection “materiales docentes”, and in the “Resumen” field, write a summary about the software you are uploading, and end with these two lines (naturally, replacing with your version’s Software Heritage identifier and your public repository URL):
> SWHID: {Software Heritage identifier}
> Repository: {public repository URL}

  • Upload as the document to be deposited the PDF file you generated earlier.

  • Include as an attached file the compressed file you downloaded from Software Heritage.

Reference in the application form:

In the application form for the Recognition of Open Subjects Call, in the section corresponding to the category “Other materials”:

  • Write the BURJC Digital URL.

  • Write a text explaining how you believe the software meets the evaluation criteria, as you would do with, for example, the subject notes.

Software Heritage browser extension.

The Software Heritage extension can be installed in both Firefox and Chrome, which allows you to conveniently check the archiving status of a repository hosted on GitHub or GitLab, request the archive update, obtain its SWHID, or even the compressed file with its contents.

References

It may be useful, before composing the repository, to consult the guide Free software publication.