This is the repository for the AMC Github workshop website.
A repository is a collection of files (web pages, images, code, etc) used for a project.
- What is this all about?
- How to contribute to this repository and website
- Learning git
- Other resources
If you'd like to collaborate with people on software, understanding Github and git can be really useful to you! It can also be useful for non-code digital projects.
The skills taught in this workshop are especially useful for open source software. If you're not familiar, check out this talk and this blog by Sumana Hareshiwara to learn more.
This project is also a bit of an introduction to static site generation, a secure and very fast method of creating websites.
There are a few ways you can contribute. You will need to be logged in to your Github account to do any of these.
See a problem? Think something could be better? Create an issue!
- Go to the Issues.
- Click "New Issue".
- Write your problem or idea.
- Click "Submit new issue".
More information about issues:
Want to fix or add something?
- Fork the repository by clicking "Fork" in the upper right hand corner. This will create a copy of the repository in your Github account.
- Make changes to your fork. If you are using only Github, edit files or create new files on the Github website and commit your changes to your fork.
- Create a pull request
on the repository that you forked from (the original repository!).
- Click "New pull request".
- You want to do a pull request between forks (different repositories), so click "compare across forks". The "base fork" is the repository that you want to add changes to; the "head fork" is the one that's yours and contains the changes. Select your fork from the dropdown.
- Look at the changes you've made -- the "diff". The left side is the original. The right side is your version. The diff only shows the parts that have changes. Things you've added are in green, things you've deleted are red.
- Click the green "Create pull request" button.
- Write a description of your changes and why you made them.
- Click "Create pull request".
We will review your pull request and, unless your changes are wantonly destructive, merge it into the project! We may need to ask questions or make changes first though. You can reply to questions or comments on the pull request page.
The ".md" files in this project are converted to web pages by the Jekyll site generator. That means each file needs Front Matter-- a few lines at the top describing the file.
Participant pages should have front matter that looks like this:
---
name: Participant Name
---
(The dashes are important!)
Other pages should have front matter like this:
---
title: My page title
layout: default
---
This is how the site generator knows what the page's title is and how to format it.
- Create a file called "{your name}.md" in the "_participants" directory. For example, I created "libby.md". Then write down your thoughts about this workshop, Allied Media Conference, or life in general! Use Markdown to format your page with headings, links, or lists. Make sure to add the front matter described above.
- Correct grammer, typos or, spelling mistaeks on the webiste or this README
- Fix broken links
- Write a better explanation of something or make an explanation clearer
- Correct an explanation that is just plain wrong!
- Add more information or additional links to your favorite resources.
- If you know CSS (Cascading Style Sheets), you can edit the style sheets and make the site look different.
- If you know HTML, you can create or edit HTML files, including the templates".
- If you know Jekyll, you can edit the static site generator configuration.
- How to Win Friends and Make Pull Requests on Github
- Of Github and Pull Requests -- a comic and notes about contributing to open source projects by Rachel Nabors
- Altassian guide for making a pull request
We didn't have time to git into learning git itself. (Feel free to make an issue demanding that hideous pun be removed!!)
As great as Github is, you can't do everything with it. You can't create a new repository or merge conflicting pull requests, among other things. If you are interested in working in open source software and/or learning to code, it is well worth your time to master the git command line tool or a git GUI (graphical user interface).
Here are some tutorials for the command line (try Open Hatch to get started using a shell):
You can also try a GUI like Github Desktop, GitX, SourceTree, or GitKraken.
As you learn, we encourage you to practice your git skills by working on this repository!!
This is a Github Pages repository. That means all the files get processed by a program called Jekyll and the resulting files are visible on "(something).github.io". Anyone can create a Github Pages website! Yes, that means you!
I am hugely indebted to The Octavia Project because their website repository helped me understand how fancy Jekyll stuff works and allowed me to simplify this repo!! :D
More resources about Jekyll and Github Pages:
- Official Jekyll docs
- Jekyll Bootstrap <- haven't tried this but could be a good way to get started
- Github's info on Jekyll configuration
- Open Hatch -- Curates projects you can contribute to
- Girl Develop IT -- Runs tech workshops, including a workshop on Github and git!
- Outreachy -- Paid internships working on free software
- 10 entry points to tech (for girls, women, and everyone)
- @YourFirstPR -- tweets welcoming open source projects