From 689da58b23eec9f3e59675c0a0a25f906d3a7305 Mon Sep 17 00:00:00 2001 From: MHindermann Date: Mon, 19 Feb 2024 15:50:26 +0100 Subject: [PATCH] update theme --- course/github/1_getting_started.md | 2 +- course/github/2_core_concepts.md | 42 ++++++++++----------- course/github/3_best_practices.md | 60 +++++++++++++++--------------- 3 files changed, 52 insertions(+), 52 deletions(-) diff --git a/course/github/1_getting_started.md b/course/github/1_getting_started.md index 2df4fbf..008352e 100644 --- a/course/github/1_getting_started.md +++ b/course/github/1_getting_started.md @@ -30,4 +30,4 @@ If you want to use your IDE instead of GitHub Desktop, you are free to do so, bu ## Useful links - [GitHub documentation](https://docs.github.com) -- [GitHub Desktop documentation](https://docs.github.com/en/desktop) +- [GitHub Desktop documentation](https://docs.github.com/en/desktop) \ No newline at end of file diff --git a/course/github/2_core_concepts.md b/course/github/2_core_concepts.md index ae813f8..f3b878e 100644 --- a/course/github/2_core_concepts.md +++ b/course/github/2_core_concepts.md @@ -10,107 +10,107 @@ date: March 4, 2024 -# Repository +## Repository _A repository is the most basic element of GitHub. They're easiest to imagine as a project's folder. A repository contains all of the project files (including documentation), and stores each file's revision history. Repositories can have multiple collaborators and can be either public or private._ From [GitHub glossary/repository](https://docs.github.com/en/get-started/learning-about-github/github-glossary#repository) -## Task 3: Create a repository on with the Github web-interface +### Task 3: Create a repository on with the Github web-interface - read the [documentation](https://docs.github.com/en/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop#cloning-a-repository) on how to create a new repository with the GitHub web-interface - create a new public "test"-repository and include a README file with the web-interface -# Commit +## Commit _A commit, or "revision", is an individual change to a file (or set of files). When you make a commit to save your work, Git creates a unique ID (a.k.a. the "SHA" or "hash") that allows you to keep record of the specific changes committed along with who made them and when. Commits usually contain a commit message which is a brief description of what changes were made._ From [GitHub glossary/commit](https://docs.github.com/en/get-started/learning-about-github/github-glossary#commit) -## Task 4: Commit to a repository with the GitHub web-interface +### Task 4: Commit to a repository with the GitHub web-interface - add some text to the README file and commit the changes with the GitHub web-interface -# Clone +## Clone _A clone is a copy of a repository that lives on your computer instead of on a website's server somewhere, or the act of making that copy. When you make a clone, you can edit the files in your preferred editor and use Git to keep track of your changes without having to be online. The repository you cloned is still connected to the remote version so that you can push your local changes to the remote to keep them synced when you're online._ From [GitHub glossary/clone](https://docs.github.com/en/get-started/learning-about-github/github-glossary#clone) -## Task 5: Sign in to GitHub Desktop +### Task 5: Sign in to GitHub Desktop - read the [documentation](https://docs.github.com/en/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop#cloning-a-repository) on how to sign in to GitHub Desktop - sign in to GitHub Desktop -## Task 6: Clone a repository with GitHub Desktop +### Task 6: Clone a repository with GitHub Desktop - read the [documentation](https://docs.github.com/en/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop#cloning-a-repository) on how to clone a repository with GitHub Desktop - clone the "test"-repository with GitHub Desktop -# Push +## Push _To push means to send your committed changes to a remote repository on GitHub.com. For instance, if you change something locally, you can push those changes so that others may access them._ From [GitHub glossary/push](https://docs.github.com/en/get-started/learning-about-github/github-glossary#push) -## Task 7: Push a commit to remote with GitHub Desktop +### Task 7: Push a commit to remote with GitHub Desktop - open the README file on the local "test"-repository, add some text, and save the file - read the [documentation](https://docs.github.com/en/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#write-a-commit-message-and-push-your-changes) on how to commit and push your changes with GitHub Desktop - commit your changes to the "main"-branch of the "test"-repository with GitHub Desktop - push your changes to the remote "test"-repository with GitHub Desktop -# Branches +## Branches _A branch is a parallel version of a repository. It is contained within the repository, but does not affect the primary or main branch allowing you to work freely without disrupting the "live" version. When you've made the changes you want to make, you can merge your branch back into the main branch to publish your changes._ From [GitHub glossary/branch](https://docs.github.com/en/get-started/learning-about-github/github-glossary#branch) -## Task 8: Create a "new"-branch with the GitHub web-interface +### Task 8: Create a "new"-branch with the GitHub web-interface - read the [documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#creating-a-branch) on creating branches with the web-interface - create a branch called "new" with the web-interface -## Task 9: Commit to "new"-branch with the GitHub web-interface +### Task 9: Commit to "new"-branch with the GitHub web-interface - read the [documentation](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository) on viewing branches with the web-interface - commit a new TXT file called "hello.txt" to the "new"-branch with the web-interface -# Pull +## Pull _Pull refers to when you are fetching in changes and merging them. For instance, if someone has edited the remote file you're both working on, you'll want to pull in those changes to your local copy so that it's up to date._ From [GitHub glossary/pull](https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull) -## Task 10: Switch to "new"-branch with GitHub Desktop +### Task 10: Switch to "new"-branch with GitHub Desktop - read the [documentation](https://docs.github.com/en/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop#switching-between-branches) on switching branches with GitHub Desktop - switch to "new"-branch with GitHub Desktop -# Merge and pull requests +## Merge and pull requests _Merging takes the changes from one branch (in the same repository or from a fork), and applies them into another. This often happens as a "pull request" (which can be thought of as a request to merge), or via the command line. A merge can be done through a pull request via the GitHub.com web interface if there are no conflicting changes, or can always be done via the command line._ From [GitHub glossary/merge](https://docs.github.com/en/get-started/learning-about-github/github-glossary#merge) -## Task 11: Merge "new"-branch into main via a pull request +### Task 11: Merge "new"-branch into main via a pull request - read the [documentation](https://docs.github.com/en/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop#creating-a-pull-request) on creating a pull request with GitHub Desktop - create a pull request from "new"-branch into "main"-branch with GitHub Desktop - read the [documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request#merging-a-pull-request) on merging pull requests with the web-interface - merge the pull request with the web-interface -## Task 12: Delete the "new"-branch with the GitHub web-interface +### Task 12: Delete the "new"-branch with the GitHub web-interface - read the [documentation](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request#deleting-a-branch-used-for-a-pull-request) on deleting branches with the web-interface - delete the "new"-branch with the web-interface -# Optional tasks +## Optional tasks -## Task 13: review a pull request +### Task 13: review a pull request - read the [documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) on pull request reviews - pair up with one of your peers from this course - clone their "test"-repository - change a file and make a pull request - review their pull request to your "test"-repository -## Task 14: create and resolve a merge conflict +### Task 14: create and resolve a merge conflict - read the [documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts) on merge conflicts - create a merge conflict in your "test"-repository - try to resolve the merge conflict -# Useful links +## Useful links - [GitHub glossary](https://docs.github.com/en/get-started/learning-about-github/github-glossary#commit) - [GitHub documentation](https://docs.github.com) diff --git a/course/github/3_best_practices.md b/course/github/3_best_practices.md index bc290e4..10259ea 100644 --- a/course/github/3_best_practices.md +++ b/course/github/3_best_practices.md @@ -8,97 +8,97 @@ date: March 4, 2024 # GitHub best practices -# Documentation and FAIR data +## Documentation and FAIR data Documentation and FAIR data principles are crucial in research for ensuring transparency, reproducibility, and efficiency. Documentation provides clear records of research processes, while FAIR principles (Findability, Accessibility, Interoperability, Reusability) ensure data is easily shared and used. These practices collectively enhance the integrity and impact of research. -## README.md +### README.md _You can add a README file to your repository to tell other people why your project is useful, what they can do with your project, and how they can use it._ From the [GitHub documentation](https://docs.githubcom/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) on README files -### Materials +#### Materials - The README file of this course is [here](https://github.com/RISE-UNIBAS/clean-code/blob/main/README.md). -- README templates and suggestions on https://www.makeareadme.com/. +- README templates and suggestions on [https://www.makeareadme.com/](https://www.makeareadme.com/). -### Questions +#### Questions - What is `.md` for a file type? - What should go into a README file? - How many README files does one need? -## LICENSE.md +### LICENSE.md _Public repositories on GitHub are often used to share open source software. For your repository to truly be open source, you'll need to license it so that others are free to use, change, and distribute the software._ From the [GitHub documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository) on licensing a repository -### Materials +#### Materials - [Primer on intellectual property righs](https://researchdata.unibas.ch/en/legal-issues/intellectual-property-rights/) by the Research Data Management-Network University of Basel -- Choose a license with https://choosealicense.com/. +- Choose a license with [https://choosealicense.com/](https://choosealicense.com/). -### Questions +#### Questions - Why do you need a license for research software or research data? - What are suitable licenses in this context? -## CITATION.cff +### CITATION.cff _You can add a CITATION.cff file to the root of a repository to let others know how you would like them to cite your work. The citation file format is plain text with human- and machine-readable citation information._ From the [GitHub documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) on CITATION files -### Materials +#### Materials - The CITATION file of this course is [here](https://github.com/RISE-UNIBAS/clean-code/blob/main/CITATION.cff). - You can youse the [cffinit](https://citation-file-format.github.io/cff-initializer-javascript/#/) tool to create or update your CITATION file. -### Questions +#### Questions - What is an ORCID ID, what is a DOI? -## Releases +### Releases _GitHub's way of packaging and providing software to your users._ From [GitHub glossary/release](https://docs.github.com/en/get-started/learning-about-github/github-glossary#release) -### Materials +#### Materials - The releases of this course are [here](https://github.com/RISE-UNIBAS/clean-code/releases). - Releases should adhere to [semantic versioning](https://semver.org/spec/v2.0.0.html). - [GitHub documentation](https://docs.github.com/en/repositories/releasing-projects-on-github) on releases. -### Questions +#### Questions - What do I put in the release notes? -## Zenodo pipeline +### Zenodo pipeline GitHub repositories can be published to [Zenodo](https://zenodo.org/) as releases. -### Materials +#### Materials - [GitHub documentation](https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content#issuing-a-persistent-identifier-for-your-repository-with-zenodo) on issuing a persistent identifier for your repository with Zenodo- -- A more detailed documentation is here. +- A more detailed documentation is [here](zenodo_pipeline.md). -## CHANGELOG.md +### CHANGELOG.md _A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project._ -From https://keepachangelog.com/en/1.1.0/ +From [https://keepachangelog.com/en/1.1.0/](https://keepachangelog.com/en/1.1.0/) -### Materials +#### Materials - The CHANGELOG file of this course is [here](https://github.com/RISE-UNIBAS/clean-code/blob/main/CHANGELOG.md). -- CHANGELOG templates and suggestions on https://keepachangelog.com/en/1.1.0/. +- CHANGELOG templates and suggestions on [https://keepachangelog.com/en/1.1.0/](https://keepachangelog.com/en/1.1.0/). -### Questions +#### Questions - Why keep a changelog? - Who needs a changelog? -## GitHub pages +### GitHub pages https://docs.github.com/en/pages https://github.com/nicolas-van/easy-markdown-to-github-pages?tab=readme-ov-file -# Security +## Security -## Secrets +### Secrets - login credentials, API keys... - -# Collaboration +## Collaboration - pull requests - branch protection @@ -106,18 +106,18 @@ https://github.com/nicolas-van/easy-markdown-to-github-pages?tab=readme-ov-file - issues - project management tools -# Automation +## Automation - [Documentation](https://docs.github.com/en/actions) on GitHub actions -# Getting help +## Getting help - Documentation (see links below) - Google is your friend - [Stackoverflow](https://stackoverflow.com/) - GPTs -# Useful links +## Useful links - [GitHub glossary](https://docs.github.com/en/get-started/learning-about-github/github-glossary#commit) - [GitHub documentation](https://docs.github.com)