From 19f807a2e6547ae1118b00244c01ad297f2c075e Mon Sep 17 00:00:00 2001 From: Allegra Via Date: Fri, 4 Oct 2019 18:19:08 +0200 Subject: [PATCH 1/6] Update 02-make-it-public.md markdown --- _episodes/02-make-it-public.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/_episodes/02-make-it-public.md b/_episodes/02-make-it-public.md index 92ee13a..ef42496 100644 --- a/_episodes/02-make-it-public.md +++ b/_episodes/02-make-it-public.md @@ -58,6 +58,9 @@ on this topic, and other advice on starting an open source project, check out th - This file is automatically displayed on the front page of your repository - It has important information about your project + The '.md' extension indicates that a file is written in Markdown language, which uses plain text formatting syntax. + + To format the contents of this file you will use Markdown syntax. If you want to know more about it you can use this [cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) or this [short guide](https://guides.github.com/features/mastering-markdown/) @@ -71,7 +74,7 @@ on this topic, and other advice on starting an open source project, check out th {: .challenge} - In addition to the README & LICENSE (.md) files, a good software project might include guidance for contributing to the project (CONTRIBUTING.md - see lesson on contributions, governance, and communication), details of how to correctly cite the software after publication (CITATION.md - see later in this lesson), or even a `paper.md` file if the software is published via the Journal of Open Source Software (JOSS) -- You should have a good idea of what is the appropriate license for your project after the [next lesson](https://softdev4research.github.io/4OSS-lesson/03-use-license/index.html) but, if you need help choosing an license, you can also click on the "info" button next to the "add a license" dropdown, which will take you to https://choosealicense.com/ +- You should have a good idea of what is the appropriate license for your project after the [next lesson](https://softdev4research.github.io/4OSS-lesson/03-use-license/index.html) but, if you need help to choose a license, you can also click on the "info" button next to the "add a license" dropdown, which will take you to https://choosealicense.com/ - Making the project public at the start is not enough! See the [Software Carpentry lesson on Version Control with Git](http://swcarpentry.github.io/git-novice/) for advice on best practice in software version control. > ## Discussion: How does version control help your project? From 3458d05a7c8d4ef4e21e7cd979c9cfe3cbf085d6 Mon Sep 17 00:00:00 2001 From: Allegra Via Date: Sun, 6 Oct 2019 20:03:28 +0200 Subject: [PATCH 2/6] Update 02-make-it-public.md more on Markdown --- _episodes/02-make-it-public.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/_episodes/02-make-it-public.md b/_episodes/02-make-it-public.md index ef42496..f70eb24 100644 --- a/_episodes/02-make-it-public.md +++ b/_episodes/02-make-it-public.md @@ -58,19 +58,29 @@ on this topic, and other advice on starting an open source project, check out th - This file is automatically displayed on the front page of your repository - It has important information about your project - The '.md' extension indicates that a file is written in Markdown language, which uses plain text formatting syntax. + The '.md' extension indicates that the file is written in Markdown language, which uses plain text formatting syntax that can be converted into web output format. Markdown syntax is basically plain text with a few non-alphabetic characters such as * or # for bold, italics, headings, etc. to style test. For example, you can make some text bold by adding two asterisks \** before and after the text: - - To format the contents of this file you will use Markdown syntax. If you want to know more about it you can use this [cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) or this [short guide](https://guides.github.com/features/mastering-markdown/) - +``` +**This text is bold** +``` +will appear as: +**This text is bold** + +It is also possible to create lists, insert images, tables, web links and more. + +We will see now some basic writing and formatting syntax by following this [short guide](https://guides.github.com/features/mastering-markdown/). This [cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) also provide useful guidance. + > ## Challenge: Improve the README > > The README.md file that GitHub generated when we created the project is quite > boring. Add some more content using some of the Markdown syntax introduced -> above. You could add a few sentences about the purpose of your software, some +> above (if you don't remember a Markdown command you can refer to the +> [cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) mentioned above). +> You could add a few sentences about the purpose of your software, some > details of the author(s) and their affiliation(s), or anything else that you > think is important. +> {: .challenge} - In addition to the README & LICENSE (.md) files, a good software project might include guidance for contributing to the project (CONTRIBUTING.md - see lesson on contributions, governance, and communication), details of how to correctly cite the software after publication (CITATION.md - see later in this lesson), or even a `paper.md` file if the software is published via the Journal of Open Source Software (JOSS) From bb3f2eb5bf11c09edcb791e45a6033e432a96fbd Mon Sep 17 00:00:00 2001 From: Allegra Via Date: Sun, 6 Oct 2019 23:47:06 +0200 Subject: [PATCH 3/6] Update 02-make-it-public.md --- _episodes/02-make-it-public.md | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/_episodes/02-make-it-public.md b/_episodes/02-make-it-public.md index f70eb24..199915f 100644 --- a/_episodes/02-make-it-public.md +++ b/_episodes/02-make-it-public.md @@ -69,7 +69,7 @@ will appear as: It is also possible to create lists, insert images, tables, web links and more. -We will see now some basic writing and formatting syntax by following this [short guide](https://guides.github.com/features/mastering-markdown/). This [cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) also provide useful guidance. +We will see now some basic writing and formatting syntax by following this [short guide](https://guides.github.com/features/mastering-markdown/). This [cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) also provides useful guidance. > ## Challenge: Improve the README > @@ -80,13 +80,43 @@ We will see now some basic writing and formatting syntax by following this [shor > You could add a few sentences about the purpose of your software, some > details of the author(s) and their affiliation(s), or anything else that you > think is important. -> {: .challenge} +In addition to the README.md file, a good software project should include other "recommended community health files". What other files should you include in your project? If your project is hosted on GitHub, you may refer to the [GitHub Community Profile](https://help.github.com/en/articles/accessing-a-projects-community-profile). In general, a public repository Community Profile provides guidance and best practices about how to help grow a community and support contributors. +[Here](https://github.com/SoftDev4Research/4OSS-lesson/community) you can find the GitHub Community Profile checklist, which can be used to see if your project includes community health files recommended by GitHub. These include a project DESCRIPTION.md file, a README file and a code of conduct, which contains standards on how to engage in the community. Furthermore, a project should have a CONTRIBUTING.md file (for details see episode on "Define clear and transparent contribution, governance and communication processes") outlining guidance for contributing to the project, a LICENCE.md file that states how the code can be used, details of how to correctly cite the software after publication (CITATION.md - see later in this episode), or even a `paper.md` file if the software is published via the Journal of Open Source Software (JOSS). Templates for GitHub issues and pull requests are also required for a complete community profile (see the [Software Carpentry lesson on Version Control with Git](http://swcarpentry.github.io/git-novice/)to learn about GitHub issues and pull requests). +You should have a good idea of what is the appropriate license for your project after the [next episode](https://softdev4research.github.io/4OSS-lesson/03-use-license/index.html) but, if you need help to choose a license, you can also click on the "info" button next to the "add a license" dropdown, which will take you to https://choosealicense.com/ + +DA QUI + +DEVI AGGIUNGERE UNA CHALLENGE + +Additional files provide insight on: how to contibute to the project + +> ## Challenge: What other files? +> + +might include guidance for contributing to the project (CONTRIBUTING.md - see lesson on contributions, governance, and communication), details of how to correctly cite the software after publication (CITATION.md - see later in this lesson), or even a `paper.md` file if the software is published via the Journal of Open Source Software (JOSS) + +Exercise: what other files? (this should be arround community insight page, Allegra) +GitHub Insights Community +https://github.com/SoftDev4Research/4OSS-lesson/community +Add explanation for community profile and explain README files and say other files will be explained in detail in relevant sections (Allegra) +CONTRIBUTING.md +CITE.cff +why citation? +we need recognition for software and that will not happen if there is no way to cite software +COC +requirements.txt/environment.yml +CHANGELOG.md +metadata description (codemeta, schema.org, requirements by different journal eg. SoftwareX) +license + - In addition to the README & LICENSE (.md) files, a good software project might include guidance for contributing to the project (CONTRIBUTING.md - see lesson on contributions, governance, and communication), details of how to correctly cite the software after publication (CITATION.md - see later in this lesson), or even a `paper.md` file if the software is published via the Journal of Open Source Software (JOSS) - You should have a good idea of what is the appropriate license for your project after the [next lesson](https://softdev4research.github.io/4OSS-lesson/03-use-license/index.html) but, if you need help to choose a license, you can also click on the "info" button next to the "add a license" dropdown, which will take you to https://choosealicense.com/ - Making the project public at the start is not enough! See the [Software Carpentry lesson on Version Control with Git](http://swcarpentry.github.io/git-novice/) for advice on best practice in software version control. +A QUI + > ## Discussion: How does version control help your project? > #### 5 minutes > You may already be aware of the benefits of software version control in relation to a programming project. In small groups, discuss how following best practices in version control, such as making regular, small, self-contained commits, and having project members work on branches to avoid conflicts, can benefit a project hosted publicly on GitHub. From d165551732f8cd8bac4e4fdf7651809b29b2f067 Mon Sep 17 00:00:00 2001 From: Allegra Via Date: Mon, 7 Oct 2019 17:05:39 +0200 Subject: [PATCH 4/6] Update 02-make-it-public.md health files --- _episodes/02-make-it-public.md | 41 +++++++++------------------------- 1 file changed, 10 insertions(+), 31 deletions(-) diff --git a/_episodes/02-make-it-public.md b/_episodes/02-make-it-public.md index 199915f..f2b65b1 100644 --- a/_episodes/02-make-it-public.md +++ b/_episodes/02-make-it-public.md @@ -82,40 +82,19 @@ We will see now some basic writing and formatting syntax by following this [shor > think is important. {: .challenge} -In addition to the README.md file, a good software project should include other "recommended community health files". What other files should you include in your project? If your project is hosted on GitHub, you may refer to the [GitHub Community Profile](https://help.github.com/en/articles/accessing-a-projects-community-profile). In general, a public repository Community Profile provides guidance and best practices about how to help grow a community and support contributors. -[Here](https://github.com/SoftDev4Research/4OSS-lesson/community) you can find the GitHub Community Profile checklist, which can be used to see if your project includes community health files recommended by GitHub. These include a project DESCRIPTION.md file, a README file and a code of conduct, which contains standards on how to engage in the community. Furthermore, a project should have a CONTRIBUTING.md file (for details see episode on "Define clear and transparent contribution, governance and communication processes") outlining guidance for contributing to the project, a LICENCE.md file that states how the code can be used, details of how to correctly cite the software after publication (CITATION.md - see later in this episode), or even a `paper.md` file if the software is published via the Journal of Open Source Software (JOSS). Templates for GitHub issues and pull requests are also required for a complete community profile (see the [Software Carpentry lesson on Version Control with Git](http://swcarpentry.github.io/git-novice/)to learn about GitHub issues and pull requests). -You should have a good idea of what is the appropriate license for your project after the [next episode](https://softdev4research.github.io/4OSS-lesson/03-use-license/index.html) but, if you need help to choose a license, you can also click on the "info" button next to the "add a license" dropdown, which will take you to https://choosealicense.com/ +In addition to the README.md file, a good software project should include other "recommended community health files". What other files should you include in your project? You may find insights on health files to include in your project (to ensure that it meets the recommended community standards) in the Community Profile of the public repository hosting your project. Indeed, a public repository Community Profile provides rules and best practices on how to help grow a community and support contributors in using and contributing to your project. If your project is hosted on GitHub, you may refer to the [GitHub Community Profile](https://github.com/SoftDev4Research/4OSS-lesson/community), which can be accessed following [these instructions](https://help.github.com/en/articles/accessing-a-projects-community-profile) and where you can find a checklist that can be used to see if your project includes community health files recommended by GitHub. +These include a project DESCRIPTION file, a README file and a CODE_OF_CONDUCT, which contains standards on how to engage in the community. Furthermore, a project should have a CONTRIBUTING file (for details see episode on "Define clear and transparent contribution, governance and communication processes") outlining guidance for contributing to the project, and a LICENCE file that states how the code can be used. You should have a good idea of what is the appropriate license for your project after the [next episode](https://softdev4research.github.io/4OSS-lesson/03-use-license/index.html). Templates for GitHub issues and pull requests are also required for a complete community profile (see the [Software Carpentry lesson on Version Control with Git](http://swcarpentry.github.io/git-novice/) to learn about GitHub issues and pull requests). -DA QUI +You might also want to add details of how to correctly cite the software after publication. This can be done by adding a file called CITATION.cff in the root of your repository (where other health files are stored). The .cff (Citation File Format) is a machine-readble and human-readble and -writable format providing citation information for research software. +You may also add a `paper.md` file if the software is published via the Journal of Open Source Software (JOSS). +Notice that you, as a research/scientific software developer, need recognition for software you develop and this will not happen if there is no way to cite your software. -DEVI AGGIUNGERE UNA CHALLENGE - -Additional files provide insight on: how to contibute to the project - -> ## Challenge: What other files? -> - -might include guidance for contributing to the project (CONTRIBUTING.md - see lesson on contributions, governance, and communication), details of how to correctly cite the software after publication (CITATION.md - see later in this lesson), or even a `paper.md` file if the software is published via the Journal of Open Source Software (JOSS) - -Exercise: what other files? (this should be arround community insight page, Allegra) -GitHub Insights Community -https://github.com/SoftDev4Research/4OSS-lesson/community -Add explanation for community profile and explain README files and say other files will be explained in detail in relevant sections (Allegra) -CONTRIBUTING.md -CITE.cff -why citation? -we need recognition for software and that will not happen if there is no way to cite software -COC -requirements.txt/environment.yml -CHANGELOG.md -metadata description (codemeta, schema.org, requirements by different journal eg. SoftwareX) -license - -- In addition to the README & LICENSE (.md) files, a good software project might include guidance for contributing to the project (CONTRIBUTING.md - see lesson on contributions, governance, and communication), details of how to correctly cite the software after publication (CITATION.md - see later in this lesson), or even a `paper.md` file if the software is published via the Journal of Open Source Software (JOSS) -- You should have a good idea of what is the appropriate license for your project after the [next lesson](https://softdev4research.github.io/4OSS-lesson/03-use-license/index.html) but, if you need help to choose a license, you can also click on the "info" button next to the "add a license" dropdown, which will take you to https://choosealicense.com/ -- Making the project public at the start is not enough! See the [Software Carpentry lesson on Version Control with Git](http://swcarpentry.github.io/git-novice/) for advice on best practice in software version control. +> ## Challenge: Add a CITATION.cff file to your repository +> You can use the example provided [here](https://citation-file-format.github.io) to create a CITATION.cff +> file for your software and add it to your repository. +{: .challenge} -A QUI +You will find more about how to publish your software later in this episode. Other health files will be described in detail in relevant sections. > ## Discussion: How does version control help your project? > #### 5 minutes From 7038c687354fa3e67700e6769bc79d118636a9e2 Mon Sep 17 00:00:00 2001 From: Allegra Via Date: Mon, 7 Oct 2019 17:06:48 +0200 Subject: [PATCH 5/6] Update 02-make-it-public.md --- _episodes/02-make-it-public.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_episodes/02-make-it-public.md b/_episodes/02-make-it-public.md index f2b65b1..d653eca 100644 --- a/_episodes/02-make-it-public.md +++ b/_episodes/02-make-it-public.md @@ -80,6 +80,7 @@ We will see now some basic writing and formatting syntax by following this [shor > You could add a few sentences about the purpose of your software, some > details of the author(s) and their affiliation(s), or anything else that you > think is important. + {: .challenge} In addition to the README.md file, a good software project should include other "recommended community health files". What other files should you include in your project? You may find insights on health files to include in your project (to ensure that it meets the recommended community standards) in the Community Profile of the public repository hosting your project. Indeed, a public repository Community Profile provides rules and best practices on how to help grow a community and support contributors in using and contributing to your project. If your project is hosted on GitHub, you may refer to the [GitHub Community Profile](https://github.com/SoftDev4Research/4OSS-lesson/community), which can be accessed following [these instructions](https://help.github.com/en/articles/accessing-a-projects-community-profile) and where you can find a checklist that can be used to see if your project includes community health files recommended by GitHub. @@ -92,6 +93,7 @@ Notice that you, as a research/scientific software developer, need recognition f > ## Challenge: Add a CITATION.cff file to your repository > You can use the example provided [here](https://citation-file-format.github.io) to create a CITATION.cff > file for your software and add it to your repository. + {: .challenge} You will find more about how to publish your software later in this episode. Other health files will be described in detail in relevant sections. From 7bc83e35908629671086f45ba665d9b3c3da280e Mon Sep 17 00:00:00 2001 From: Allegra Via Date: Mon, 7 Oct 2019 17:16:19 +0200 Subject: [PATCH 6/6] 02-make-it-public.md improved challenge .cff --- _episodes/02-make-it-public.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/_episodes/02-make-it-public.md b/_episodes/02-make-it-public.md index d653eca..b22c13d 100644 --- a/_episodes/02-make-it-public.md +++ b/_episodes/02-make-it-public.md @@ -92,7 +92,8 @@ Notice that you, as a research/scientific software developer, need recognition f > ## Challenge: Add a CITATION.cff file to your repository > You can use the example provided [here](https://citation-file-format.github.io) to create a CITATION.cff -> file for your software and add it to your repository. +> file for your software and add it to your repository. It is not relevant to use real information for this exercise. +> It is important that you see how to write a .cff file and to include it in your repository. {: .challenge}