diff --git a/_config.yml b/_config.yml index 6f831f6..1a66b4a 100644 --- a/_config.yml +++ b/_config.yml @@ -18,12 +18,13 @@ title: GitHub For Researchers # Name of the workshop description: | - This is just to make changes. Revert back as soon as possible. + This is a general tutorial on using Git and GitHub with a bit of an emphasis on + how researchers might use the tools for their work. # Author information author: - name: Robert Olendorf + name: Robert Olendorf & Shaun Bennett # url: http://example.com/ company: name: NC State University diff --git a/_config_dev.yml b/_config_dev.yml index a0148a4..e469d4a 100644 --- a/_config_dev.yml +++ b/_config_dev.yml @@ -3,7 +3,7 @@ # on a local server. Then GitHub will not use the _config.dev.yml file so the settings # there will take over. SEe https://github.com/jekyll/jekyll/issues/958 . -supporting_files_path: "supporting_files/" +supporting_files_path: "/supporting_files/" # Where the bibliography data is comment out or set to blank to disable. title: Git and GitHub (DEV)) diff --git a/_slides/introductions.md b/_slides/introductions.md deleted file mode 100644 index f8a6c39..0000000 --- a/_slides/introductions.md +++ /dev/null @@ -1,11 +0,0 @@ ---- - -order: 30 - ---- - -# Introductions - - - - diff --git a/_units/basic_versioning.md b/_units/basic_versioning.md index 2287a10..35eddfd 100644 --- a/_units/basic_versioning.md +++ b/_units/basic_versioning.md @@ -4,7 +4,7 @@ title: Basic Versioning order: 10 -duration: 10 +duration: 15 tutorial: true instructors_notes: true diff --git a/_units/collaborating_with_github.md b/_units/collaborating_with_github.md index 2c3b70f..ee41436 100644 --- a/_units/collaborating_with_github.md +++ b/_units/collaborating_with_github.md @@ -4,7 +4,7 @@ title: Collaborating With GitHub # This is required order: 30 -duration: 20 +duration: 10 tutorial: true # Set to true if you want this page displayed as a web page instructors_notes: true # Set to true if you want this displayed in instructors notes @@ -15,26 +15,14 @@ description: | several conventions that facilitate collaboration. In this unit, you learn how to add collaborators and work with them on a single repository. - In this section, we will learn how to copy repositories, add collaborators - to our own repositories and even collaborate with people we may not know at all. + - Copy Repositories + - Add collaborators + - Manage permissions + - Pull Requests. instructors_note: | - This is pulled from `page.instructors_note`, and combined with the - `page.description` field. - -# These should resolve to files in the supporting_files directory -# or if you specified a different one in _config.yml use that. -# The link_text can be anything you want. -# supporting_files: -# - file: -# file_name: first_example_file.txt -# link_text: Example file for this unit. -# - file: -# file_name: another_example_file.png -# link_text: Example image for this unit. - --- ## Add A Collaborator diff --git a/_units/gh_pages.md b/_units/gh_pages.md index a5fad45..4763649 100644 --- a/_units/gh_pages.md +++ b/_units/gh_pages.md @@ -20,11 +20,7 @@ description: | just publish a simple page based on the content we have already created. instructors_note: | - This is pulled from `page.instructors_note`, and combined with the - `page.description` field. - - This is not shown in the tutorial pages because `page.tutorial: false`. - + # These should resolve to files in the supporting_files directory @@ -40,8 +36,10 @@ instructors_note: | --- -If you want more of a web page feel than a Wiki can give you, GitHub also allows you to generate static web pages. A full tutorial on -GitHub pages is far beyond our scope here, but to try it out quickly. +If you want more of a web page feel than a Wiki can give you, GitHub also allows you to +generate static web pages. This workshop and tutorial are actually devlivered via GitHub +pages. A full tutorial on GitHub pages is far beyond our scope here, +but to try it out quickly. Create a new branch called **_gh-pages_**. @@ -57,6 +55,8 @@ This is my first GitHub Pages page! Then go to your project settings and scroll down to the GitHub pages section. You will see a notice, and once its green and says its published, follow the link to your new page. +Status display for github pages + If you read the [documentation](https://help.github.com/en/articles/configuring-a-publishing-source-for-github-pages) you will see there are other ways to organize your GitHub pages as well. There is a lot you can do with GitHub pages. Not only do people write documentation for their projects, but you can put personal websites up, presentation slides, even this tutorial diff --git a/_units/github_ecosystem.md b/_units/github_ecosystem.md index 861e3d4..f1d098b 100644 --- a/_units/github_ecosystem.md +++ b/_units/github_ecosystem.md @@ -4,7 +4,7 @@ title: The GitHub Ecosystem order: 50 -duration: 5 +duration: 0 tutorial: true instructors_notes: true @@ -16,10 +16,7 @@ description: | GitHub's open APIs. The remainder of this tutorial surveys some of these services. instructors_note: | - This is pulled from `page.instructors_note`, and combined with the - `page.description` field. - - This is not shown in the tutorial pages because `page.tutorial: false`. + diff --git a/_units/github_wiki.md b/_units/github_wiki.md index d37ed1f..ceeefbe 100644 --- a/_units/github_wiki.md +++ b/_units/github_wiki.md @@ -4,7 +4,7 @@ title: GitHub Wiki order: 50 -duration: 15 +duration: 10 tutorial: true instructors_notes: true @@ -13,25 +13,11 @@ instructors_notes: true # notation for this. description: | Each GitHub project comes with its own Wiki. This is very handy for extended documentation, + meeting notes, and other aspects of a project. instructors_note: | - This is pulled from `page.instructors_note`, and combined with the - `page.description` field. - - This is not shown in the tutorial pages because `page.tutorial: false`. - - - -# These should resolve to files in the supporting_files directory -# or if you specified a different one in _config.yml use that. -# The link_text can be anything you want. -# supporting_files: -# - file: -# file_name: first_example_file.txt -# link_text: Example file for this unit. -# - file: -# file_name: another_example_file.png -# link_text: Example image for this unit. + Give a little time to make a page or two. + --- diff --git a/_units/impact_and_analytics.md b/_units/impact_and_analytics.md index 6513bf5..474763b 100644 --- a/_units/impact_and_analytics.md +++ b/_units/impact_and_analytics.md @@ -2,11 +2,11 @@ layout: page # This is required title: Impact and Analytics # This is required -order: 80 # Determines the order of units. Doesn't need to be consecutive though +order: 45 # Determines the order of units. Doesn't need to be consecutive though # or even start with zero, the pages will be displayed in their sort # order. -duration: 15 # A hint to how long it will take to cover this topic in mintues. +duration: 10 # A hint to how long it will take to cover this topic in mintues. tutorial: true # Set to true if you want this page displayed as a web page instructors_notes: true # Set to true if you want this displayed in instructors notes @@ -14,13 +14,12 @@ instructors_notes: true # Set to true if you want this displayed in instructors # Provide a brief description of what the unit is about. You can use markdown # notation for this. description: | - This is pulled from the `page.description` field. + The impact and analytic numbers are useful not only from a project management standpoint, + but can also help users decide if a project is worth using in their own work. instructors_note: | - This is pulled from `page.instructors_note`, and combined with the - `page.description` field. + Show and tell of the different information shown for a project. - This is not shown in the tutorial pages because `page.tutorial: false`. @@ -37,39 +36,79 @@ instructors_note: | --- -## An Opinionated Framework +GitHub provides a number of ways to see the activity and status of a repository. There is +quite a bit of information just on the splash page. The image below is taken from a +popular web development framework [Ruby on Rails](https://github.com/rails/rails). + +Impact for ruby on rails shown on the splash page + +Working top to bottom, we first see how many projects are using this framework ( **Used by**, 1.2 million). +**Watchers**, who get updates about the project. **Stars**, that represent people who like the project. +Stars also function something like bookmarks. Finally **Forks**, which we have talked about, that +are copies of a repository. All of these things give you an idea of how useful and popular a +project might be. + +Below that we see the number of open issues and open pull requests. This can give you an +idea of how well the project maintainers are doing in keeping up with bugs, suggested +features. If you scan through the issues and pull requests you can also get an idea of how fast +they get handled. The first page of Ruby on Rails issues are mostly just a few hours old +at the time of writing. + +Below that you can see the number of commits, branches, releases and contributes. If you click on the +colored bar, you will see the languages that appear in the code base for this project. + +Ruby on Rails is a popular and very active project with lots of contributors and a fairly large base of users. In short, +we can say it has a large, active and supportive community for an open source project. + +If you click on the **Insights** tab , you will be taken to more information about the project. + +Insights pulse view + +You can look through the different information on the sidebar. Contributors can tell +you who the biggest contributors are. Commits and code frequency give you more detailed +information about the activity in the project. The network and forks provide a view into +how the projects branches and forks. + +## Analytics for Project Management + +If you are a maintainer or manager for a project, these analytics can be useful for +making sure your project stays on track. You can also identify potential issues into how +commits, branches and forks are being handled. + +## Choosing A Project To Used + +One of the most common reasons researchers use GitHub is to use other people's work. You +can use these analytics to help you decide if you can use a project for your own work. +For instance, lets say there is an R package on GitHub you are considering using. + +You would first go to the splash page and look at the README. A well maintained and +written README is a good sign. It should give you a pretty good idea how to use the +project. + +Then you would look at the activity shown on the file list, the issues and pull requests. +If there has been recent activity and the issues seem to be handled quickly that is also +a good sign. If the last activity was 5 years ago, perhaps it would be better to find +another alternative as this project might be dead (or you could adopt the project as +your own by forking it.) + +Then you might go to the activity pages, look at the collaborator, see when the commits +where. + +There is no hard and fast rule for when you should use or not use a project. It depends +not only on the status of the project you are considering, but also on what other +alternatives exists and also your own tolerance for frustration. -Apprentice is a Jekyll template for creating workshops. The concept was to -make it easy to create a hands-on workshop, or even better, multiple workshops, -with a consistent structure and feel. It is opinionated in that it makes certain -assumptions about what a good workshop should be. -While the focus is on in person, hands-on learning, there should also -be a strong online component that learners can come back to as needed. -The content should be organized and open to all to view. -The content in a workshop shouldn't rely on the creators' or past -instructors to be viable. Enough information should be given to allow reuse. -The workshops should be *web friendly* in that they are easily indexed -and display well on browsers with no additional software needed. -The framework should be as easy as possible for instructors and content -creators to use and create workshops with. In practice, creating a -Power Point presentation may be easier for one workshop, but it would not -fulfill most of the other requirements. -## Structure -Apprentice is composed of these parts. -- A highly informative home page -- An online tutorial that mirrors the content of the workshop -- Instructors notes and timeline for in-person workshops -- Presentation Slides for additional information -- Clearly defined prerequisites -- Clearly defined learning goals and objectives diff --git a/_units/introduction.md b/_units/introduction.md index 3cf97b0..e2405c2 100644 --- a/_units/introduction.md +++ b/_units/introduction.md @@ -20,13 +20,9 @@ instructors_note: | This initial part is a brief slide presentation to present some fundamental concepts. Also allows time for late arrivals. - ## History of Git - ## History of GitHub - ## What versioning is - ## Git Structure - - Branches (trees vs network) - - Relationship to other repositories - ## What we will cover + - Brief introduction and history of Git + - Centralize, Distributed and Decentralized Networks + - Brief introduction and history to GitHub --- diff --git a/_units/more_collaborating.md b/_units/more_collaborating.md index 64afe74..2837d16 100644 --- a/_units/more_collaborating.md +++ b/_units/more_collaborating.md @@ -4,7 +4,7 @@ title: More Collaboration # This is required order: 35 -duration: 15 +duration: 10 tutorial: true # Set to true if you want this page displayed as a web page instructors_notes: true # Set to true if you want this displayed in instructors notes @@ -12,23 +12,14 @@ instructors_notes: true # Set to true if you want this displayed in instructors description: | This section expands on collaborating to introduce collaborating with people even if they aren't listed as collaborators. + + - Submitting Issues + - Fork repositories + - Create pull requests to original repository. instructors_note: | - This is pulled from `page.instructors_note`, and combined with the - `page.description` field. - - -# These should resolve to files in the supporting_files directory -# or if you specified a different one in _config.yml use that. -# The link_text can be anything you want. -# supporting_files: -# - file: -# file_name: first_example_file.txt -# link_text: Example file for this unit. -# - file: -# file_name: another_example_file.png -# link_text: Example image for this unit. + --- @@ -54,8 +45,7 @@ is alsoindexed by the search engines. ## Submitting an External Pull Request If you are really feeling helpful or motivated, you can also contribute directly to a project via a pull request. Of course you have already learned -about pull requests, but not how to do them when you aren't a collaborator. There is just one more thing to learn to do this. You need to **_fork_** the repository. -This is another way to make a copy of a repository. +about pull requests, but not how to do them when you aren't a collaborator. There is just one more thing to learn to do this. You need to **_fork_** the repository. Go to this [test repository](https://github.com/olendorf/hellogitworld.git) and click on the **_Fork_** button. It may ask you where to put it, just choose your own account. Now you have your own version of my play repository (which I forked from someone else!). Makes some edits and commit them. @@ -63,6 +53,8 @@ Now you can make a pull request. Click **_Pull requests_**, then click the green use the *develop* branch. Set the compare to your repository and the develop branch. Click **_Create pull request_** and give a nice title and description. Click **_Create pull request_** again and the requst will be posted to the repository. +Screen shot for creating a pull request to an external repo. + At this point, the repository owner or maintainer will review your changes. Any questions will be posted as comments on the pull request issue, and ideally answered by you. Once everything is acceptable, the changes will be merged into the project. Again, all the of this is recorded and typically web searchable too. You also become a contribute to the repository so you get recognition for your work. diff --git a/_units/other_services.md b/_units/other_services.md new file mode 100644 index 0000000..f70d2a1 --- /dev/null +++ b/_units/other_services.md @@ -0,0 +1,70 @@ +--- +layout: page # This is required +title: Useful External Github Services # This is required + +order: 70 # Determines the order of units. Doesn't need to be consecutive though + # or even start with zero, the pages will be displayed in their sort + # order. + +duration: 5 # A hint to how long it will take to cover this topic in mintues. + +tutorial: true # Set to true if you want this page displayed as a web page +instructors_notes: true # Set to true if you want this displayed in instructors notes + +# Provide a brief description of what the unit is about. You can use markdown +# notation for this. +description: | + There are many applications, websites and services that use Git and GitHub in some way. + The examples given here are included just to give a little taste of the sorts of things + that exist. + +instructors_note: | + + + +--- + +External services can open themselves to Git and GitHub in two ways. First, they can just +use remote repositories to allow you to create a repository on their platform. +Secondly, many services avail themselves of GitHubs APIs to integrate themselves more +deeply into GitHub. The services outlined below are just some of the many potentially +useful services you might find. It does pay off to spend a little time researching if +there is a particular need you have. We have already touched on one popular service, +[ZenHub](https://www.zenhub.com/), here are a few more. + + +## Figshare + +[Figshare](https://figshare.com/) is a popular commerical repository used by many researchers to archive +and share their work. It has a pretty easy integration into GitHub. Just go to your **application** settings (after you have an +account), and connect to GitHub. Then on the **My data** tab click on the GitHub icon to import the repository of choice. See the +[full documentation](https://knowledge.figshare.com/articles/item/how-to-connect-figshare-with-your-github-account-1) for more detail. + +## Open Science Framework + +[The Open Science Framework](https://osf.io/)(OSF) is an open source and free service for managing, archiving and sharing your work. +You can connect it to a variety of services including GitHub. Others include Box, DropBox, and Amazon S3. + +## Amazon Web Services + +[Amazon Web Services](https://aws.amazon.com/)(AWS) provides an array of services. Some of these integrate GitHub via remote. Others +integrate more closely using their APIs. If you are working on larger and collaborative projects, AWS may be a useful tool. Some of the +services that work well with GitHub are Cloud9, Code Pipeline and Code Deploy. + +## Travis CI + +[Travis CI]() is a popular tool among software developers and included here as an example of the many services that might be useful +for more software intensive projects. It is an **Continuous Integration** service that takes automated tests written for software +and runs them whenever certain types of activity are detected in a GitHub repository. It is a great way to ensure your code +is always functioning. It is often used with pull requests, only permitting them to be merged if the continuous integration tests +pass. + + + + + + + + + + diff --git a/_units/project_management.md b/_units/project_management.md index a02de8b..e1894f6 100644 --- a/_units/project_management.md +++ b/_units/project_management.md @@ -2,11 +2,11 @@ layout: page # This is required title: Project Management # This is required -order: 70 # Determines the order of units. Doesn't need to be consecutive though +order: 43 # Determines the order of units. Doesn't need to be consecutive though # or even start with zero, the pages will be displayed in their sort # order. -duration: 15 # A hint to how long it will take to cover this topic in mintues. +duration: 10 # A hint to how long it will take to cover this topic in mintues. tutorial: true # Set to true if you want this page displayed as a web page instructors_notes: true # Set to true if you want this displayed in instructors notes @@ -14,13 +14,13 @@ instructors_notes: true # Set to true if you want this displayed in instructors # Provide a brief description of what the unit is about. You can use markdown # notation for this. description: | - This is pulled from the `page.description` field. + GitHub's project management tools are some of the most recent and most useful tools + of GitHub. Some people don't even use the versioning and just use the project + management tools. For instance, one person managed the renovation of their house + using GitHub issues and GitHub Projects. instructors_note: | - This is pulled from `page.instructors_note`, and combined with the - `page.description` field. - - This is not shown in the tutorial pages because `page.tutorial: false`. + Just give a tour of the service. Give a little time to play with Github Projects. diff --git a/assets/img/github_pages/gh-pages_status.png b/assets/img/github_pages/gh-pages_status.png new file mode 100644 index 0000000..dedbf0e Binary files /dev/null and b/assets/img/github_pages/gh-pages_status.png differ diff --git a/assets/img/impact_and_analytics/insights.png b/assets/img/impact_and_analytics/insights.png new file mode 100644 index 0000000..2ee6199 Binary files /dev/null and b/assets/img/impact_and_analytics/insights.png differ diff --git a/assets/img/impact_and_analytics/insights_pulse.png b/assets/img/impact_and_analytics/insights_pulse.png new file mode 100644 index 0000000..284763d Binary files /dev/null and b/assets/img/impact_and_analytics/insights_pulse.png differ diff --git a/assets/img/impact_and_analytics/ror_splash.png b/assets/img/impact_and_analytics/ror_splash.png new file mode 100644 index 0000000..86a8d92 Binary files /dev/null and b/assets/img/impact_and_analytics/ror_splash.png differ diff --git a/assets/img/more_collaboration/pull_fork.png b/assets/img/more_collaboration/pull_fork.png new file mode 100644 index 0000000..de11498 Binary files /dev/null and b/assets/img/more_collaboration/pull_fork.png differ diff --git a/instructors_notes.md b/instructors_notes.md index c5e43fc..9af0476 100644 --- a/instructors_notes.md +++ b/instructors_notes.md @@ -8,23 +8,13 @@ layout: instructors_notes title: Instructors' Notes setup: - - title: Name of the task + - title: Computing description: | - Provide a brief description of the task. - - title: Name of another task - description: | - Provide a brief description of this task. - - title: Oh. You need a little dummy text for your mockup? How quaint. - description: | - Chicharrones quinoa brooklyn, **_subway tile_** pug la croix activated charcoal - organic meditation craft beer raclette celiac. Flannel austin craft beer - listicle gastropub lomo squid pug. 8-bit kickstarter palo santo marfa + Attendees should have computers. They should also have a bash style terminal. + Those with Macs should be fine. Those with windows will need to download + [Git for Windows](https://git-scm.com/download/win) and use the GitBash program + that comes with that. - vegan godard waistcoat selfies chartreuse letterpress. Actually hell - of 3 wolf moon live-edge, everyday carry pop-up biodiesel tbh. - Mustache irony hot chicken, hoodie roof party pickled hella sartorial - biodiesel messenger bag shaman live-edge selfies. --- -You can provide general notes and thoughts here. The time line -is pulled from the workshop units. +