amc-workshop.github.io

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?

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.

How to contribute to this repository and website

There are a few ways you can contribute. You will need to be logged in to your Github account to do any of these.

Create an issue

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:

Submit a pull request

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!).
1. Click "New pull request".
2. 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.
3. 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.
4. Click the green "Create pull request" button.
5. Write a description of your changes and why you made them.
6. 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.

Turning text into webpages

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.

Ideas for pull requests

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.

More information about pull requests

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

Learning git

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!!

How this Github Pages repository works.

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

Resources and essays on contributing to open source/free software

Resources

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

amc-workshop / amc-workshop.github.io

readme