Open Access Publishing at TUHH: Exemplary Step-by-step guide for a toolchain with TORE, GitLab, Sherpa Romeo and Zenodo
The following step-by-step guide is updated regularly and should be seen as a kind of living document. A more recent version, if available, can be viewed via the repository linked in the license note at the end of the post.
Publishing a paper as preprint would work as described in the following steps:
- You have to get an overview on possibilities to publish and open access sharing rights (further information on the websites of the TU library)
- Check the permissions of your journal or publisher where you would like to publish via Sherpa Romeo. Example for IEEE proceeding is:
Here you can see that preprints (research papers that are shared before peer review) are possible and which rules you have to follow. For example for CDC (Conference on Decision and Control) you can upload the preprint with a notice that this paper is submitted for review and afterwards you have to place a copyright notice and a DOI link of the IEEE finally published version. You are not allowed to publish the final version, just an author version with the copyright terms. See IEEE policy, section 3 for that.
-
Create a repository for your publication in our gitlab instance: TUHH – Gitlab (private repo, a public repo can be seen here). In general you create
- a repository for your paper
- a repository for your software code (See Code Section)
Use the following scheme: Year-paper-conference-FirstSixWordsOfTitleOfYourPublication (e.g. 2021-paper-ECC-A-Gradient-Descent-Method-for-Finite) while the code is in the corresponding Year-code-TitleOfYourContribution repository.
- Have in mind to add references to supplimentary material in the readme.
- Add submission or copyright terms to your paper and create a prefinal pdf. You might keep some space (Where??) to place the preprint DOI for references.
- Open tore submission page with your personal account (more details via tore help).
- Select Publications with fulltext and click on manual submission
- The next pages collect metadata:
- Title
- Authors (Add an ORCID if possible, Add Prof Werner, for example). Clicking on the magnifier allows searching for entries. Validated entries are marked with a green arrow.
- Select Language: English
- Type: Preprint
- Enter Abstract in English
- Select TUHH Institute: Type E14 and by using the magnifier select the validated entry.
- Go next
- Next page collects publisher metadata:
- These information will be updated with the final version to be submitted for publication
- Enter Date of issue: Todays date
- Go next
- License details
- License: Copyright should be selected
- Supplemented by: Here you can add your Code DOI
- Project: If you are working for a DFG program, you should reference it here
- Funder: Here you should add DFG or BMWI as Funder
- Now you get your DOI.
- Copy this DOI into your paper and compile it with this DOI. The DOI is booked but not finally registered. This will be done in the next steps
- Now, upload the pdf of your preprint
- upload pdf
- check filename (should be meaningful)
- Set embargo date if neccessary
- next
- Verfiy your submission and accept the license of TORE
- Your submission is nearly done. TUHH Library will check your submission. Either they accept it or ask you to change things. You will be emailed. Your entry is so to say, peer review on metadata level
- For now you are done. Further version have to be uploaded when the paper got accepted and you can upload the final author version to TORE. Please make sure that you reference the publisher DOI and add the correct credits to the paper.
Publish your software files related to your paper publication
You want to publish files like your source code, your data or videos in a save manner and cite them using a DOI?
The code you publish should be able to reproduce all figures you show in your publication by running one or multiple files which are than related to your figure. If your code uses special software or libraries to run, you should note them down in a dependancies and software section in a readme file of the repository. You should not include these files to your repository. Installation steps should be explained.
Than this is one way to go:
- Create a repository for your publication in our gitlab instance: TUHH – Gitlab. In general you create
- a repository for your paper (See Paper Section)
- a repository for your software code in https://collaborating.tuhh.de/ICS/ics-private/phd-students/papers (private repo) by using the following scheme: Year-code-conference-FirstSixWordsOfTitleOfYourPublication (e.g. 2021-code-ECC-A-Gradient-Descent-Method-for-Finite) while the paper is in the corresponding Year-paper-conference-TitleOfYourContribution repository.
- Upload your code by using git (You can use this repo already when starting to work on an idea: Repositories can be renamed and moved in the gitlab structure). Code should be cleaned up and except for dependancies and libraries selfcontaining. (Be careful on which branch to push, master gets automatically pushed to github, others not)
- Add a License file to the repo using templates: GPLv3 (Software) and CC-BY-SA (for all other media) and remove all lines after End of Terms and Conditions around line 625
- Add the following header lines to the beginning of each of your files. In references your refere to papers, software or tools you base on to cite them. Make sure that our license in compatible with the build on software/library/code.
```
%------
% Project: Name and Link
% Copyright:
% License:
% References:
% Authors:
%------
%---------------------------------------------------------------------------------------------
% For Paper,
% "A Gradient Descent Method for Finite Horizon Distributed Control of Discrete Time Systems"
% by Simon Heinke and Herbert Werner
% Copyright (c) Institute of Control Systems, Hamburg University of Technology. All rights reserved.
% Licensed under the GPLv3. See LICENSE in the project root for license information.
% Uses an own implementation of the work of
% "A. Vamsi and N. Elia, Design of distributed controllers realizable over arbitrary directed networks,
% IEEE Conference on Decision and Control, 2010."
% Author(s): Simon Heinke
%--------------------------------------------------------------------------------------------
```- You also might want to enter a section in the Readme file on how to cite your work. Therefore you should include bibtex code for citing authors to reference your work in their publication. E.g.:
```
@misc{1606.01540,
Author = {Greg Brockman and Vicki Cheung and Ludwig Pettersson and Jonas Schneider and John Schulman and Jie Tang and Wojciech Zaremba}, Title = {OpenAI Gym},
Year = {2016},
Eprint = {arXiv:1606.01540},
}
```Example for Readme.md from Christian Hespe:
- Create a repository at github.com/TUHH-ICS
- with the same name as in gitlab
- Give a short meaningful description
- Select public
- Click on create repository
- Ask Lennart Heeren or Patrick Göttsch to grant you maintainer rights in that particular repository
- Copy the SSH url from github
- Enable mirroring in gitlab
- Switch to your private gitlab repository
- Left menu -> Settings -> Repository -> Expand Mirroring repositories
- Paste your github url in Input the remote repository URL
- Modify it this way: ssh:// at the beginning and replace the colon after github.com with a slash. It should look like this now: ssh://git@github.com/TUHH-ICS/REPO_NAME
- Klick on Detect host keys button
- Select (although it does not seam to be clickable) in authentification method SSH Public Key
- And select Mirror only protected branches. By default only the master branch will be pushed as it is.
- Click on mirror repository to setup the mirror.
- Now you have to click on the Copy ssh public key
- After a click on the key…
- go back to GitHub;, click on Settings > Deploy Keys > Add deploy key
- Give it some title, paste the copied key in the key field and check Allow write access abd than click on Add key
- Now you can trigger the mirroring by pushing or merging into the master branch in gitlab or manually in the gitlab repo mirroring settings page
- Uploading to Zenodo
- Login to Zenodo using ** Log in with this credentials **
- user: ics@tuhh.de
- passwd: JJ^Q?…
- Click on setting->github (1),
- Click on Sync now button (2),
- and enable the repository (3, located at the end of the list),
- Then we go back to github and create a new release (4):
- Login to Zenodo using ** Log in with this credentials **
- give a version tag like v1.0
- give a meaningful title
- and some description (will also be published by zenodo)
- click on Publish Release
This automatically generates a zip of the code and this zip gets uploaded to zenodo, also automatically.
- Creating a DOI/Publishing
- Back in Zenodo click on upload at the top of the page
- Here you find your software code already published
- Since not all metadata is available on github, you have to edit your entry
- Click on the title opens the entry and shows a view as readers would see it.
- You can click on edit to add or change metadata. The next view is organised in multiple sections:
- Files: Here you can upload a new version manually. But normmaly you would choose a github release as the way to go.
- Communities: Please select Hamburg University of Technology to reference this contribution to TUHH
- Upload Type: Should already be Software
- Basic Information:
- Adjust the Title because the github repo name has been used. E.g.: Code for paper: Name of my marvellous paper
- Authors: Clean up authors list; Lastname, Firstname – Hamburg University of Technology – Institute of Control Systems – ORCID
- Add Prof Werner to this list: Werner, Herbert Hamburg University of Technology – Institute of Control Systems – 0000-0003-3456-5539
- Add a meaningful Description
- Version tag got automatically set
- Language: Choose English
- Give similar Keyword as you choose for your paper
- License: All should be okay. The License is provided in the repository. Zenodo so far does not support GPLv3.
- Funding: Select nothing
- Save the changes. And when you think they can be published, hit the publish button.
- Cite code
- use Zenodo Bibtex generator to get a bibtex entry of your code for your latex literature file – Export section (bottom right)
Put a DOI patch into the readme -> Use latest version DOI by clicking on the DOI entry (1) and copying the markdown code (2) from the window. You can add a badge to your gitlab repo as well, either in the readme (2) or by adding a batch using (3a) and (3b)
You might want to change the DOI to the DOI for the latest version:
- Updating
- Create new release on github
- update Description on zenodo
Publish your video files / data related to your publication
Use only Zenodo.
References
- https://de.qaz.wiki/wiki/Creative_Commons_license#Rights_and_obligations
- https://de.qaz.wiki/wiki/Comparison_of_free_and_open-source_software_licences#General_comparison
- https://docs.gitlab.com/ee/user/project/repository/repository_mirroring.html#setting-up-a-push-mirror-from-gitlab-to-github
- https://guides.github.com/activities/citable-code/
- https://www.tub.tuhh.de/blog/2018/07/23/machen-sie-ihre-software-auf-github-zitierfaehig/
- https://guides.github.com/activities/citable-code/
- https://writemd.rz.tuhh.de/p/p2Q9HSof0#/
Weiternutzung als OER ausdrücklich erlaubt: Dieses Werk und dessen Inhalte sind – sofern nicht anders angegeben – lizenziert unter CC BY 4.0. Nennung gemäß TULLU-Regel bitte wie folgt: Open Access Publishing at TUHH: Exemplary Step-by-step guide for a toolchain with TORE, GitLab, Sherpa Romeo and Zenodo von Patrick Göttsch, Christian Hespe, Adwait Datar, Simon Heinke und Lennart Heeren Lizenz: CC BY 4.0. Eine ggf. aktualisierte Version des Workflows kann über dieses GitLab-Repositorium abgerufen werden.
