diff --git a/docs/_static/bank.png b/docs/_static/bank.png new file mode 100644 index 00000000..0787ad6a Binary files /dev/null and b/docs/_static/bank.png differ diff --git a/docs/_static/bluff.png b/docs/_static/bluff.png new file mode 100644 index 00000000..24812254 Binary files /dev/null and b/docs/_static/bluff.png differ diff --git a/docs/_static/cowboy.png b/docs/_static/cowboy.png new file mode 100644 index 00000000..66369ca8 Binary files /dev/null and b/docs/_static/cowboy.png differ diff --git a/docs/_static/good_first_issue.png b/docs/_static/good_first_issue.png new file mode 100644 index 00000000..be3ca2a6 Binary files /dev/null and b/docs/_static/good_first_issue.png differ diff --git a/docs/_static/issues.png b/docs/_static/issues.png new file mode 100644 index 00000000..c76e16e2 Binary files /dev/null and b/docs/_static/issues.png differ diff --git a/docs/getting_started/github.rst b/docs/getting_started/github.rst index 821b97a7..1b79b20a 100644 --- a/docs/getting_started/github.rst +++ b/docs/getting_started/github.rst @@ -1,2 +1,88 @@ -Getting started with Github -=========================== \ No newline at end of file +Riding Herd on "Git"Hub - A view from the Saddle +================================================ + +These days a cowboy’s in a tough spot. +Farms are getting bought out, rodeos are going bust, and all these new-fangled robots are taking our jobs. +So what’s a cowboy to do? + +“Get off the ranch and go into coding”. +That’s what the counselors at the Cowboy Retraining Center in Travis City told me. + +.. sidebar:: + + .. image:: /_static/cowboy.png + +But I wasn’t ready to get off the ranch just yet. +Anyhow, where would I go? +Then one of them told me I could code from the ranch, “remote working”, she called it. +Now, I’ve been working “remote” my whole life. +It’s what being a cowboy is all about. +The idea that I could continue to work ‘remote’ appealed to me. +So I decided to give it a shot. + +Now, I’ll level with you, that first day of coding training was tough. +Variables, Functions, Loops. +None of that stuff made much sense to me. +And Python, as any cowboy knows, is a critter you need to dispatch - and quick – when you spot one on the trail! +But then just when I was about to throw in the towel and ride off into the sunset, the instructor tells us that the next lesson is going to be on something called “GitHub”. +I almost fell out of my saddle and, believe me, that’s not something a cowboy does very often. “This is one thing I do know something about,” I said to myself. + +Seems “GitHub was invented by a guy named ‘Torvalds’, Swedish fella. +Now I’ve met some Swedish farmers around these parts, but in my experience they don’t make for very good cowboys. +So I’m already a tad suspicious. +Anyway, ‘Git”, according to this Swedish fella, means “Goddamn Idiotic Truckload of Sh*t”. +Now if there’s one thing I can’t abide it’s cussin’, especially when there are children present and if there’s another thing, it’s Swedish farmers telling lies. +Believe you me this Torvalds fella is lying. +Any cowboy worth his spurs knows that “Git” is what you yell at the herd of cattle to get them to take their heads out of the grasses and their little hooves moving down the trail. +So without wasting any more time trying to figure out what “Git” means let’s saddle up and starting using it. +“Git”! + +Now the first thing a cowboy does when he’s riding into unfamiliar territory is to find the highest point – a bluff, a butte, the top of a mountain, what have you – to get the lay of the land. +(I know it’s tough to see, but that’s me there on top Bartlett mesa just outside of Raton). +From this vantage point, you can get the big picture: Process flows (streams) and Files. +Before we follow those, our first stop is to head into the town just over the next ridge where we can pick up some supplies – provisions and intel. + +.. sidebar:: + + .. image:: /_static/bluff.png + +Communication/Issues +-------------------- + +The best way to figure out what’s going on around here is to mosey on over to the General Store and scan the items on that notice board hanging by the side of the door. +You can do this In GitHub by going to the top bar (ribbon) and clicking on the “Issues” tab. + +.. sidebar:: + + .. image:: /_static/bank.png + +Once you click on “Issues” you’ll see what looks like a bulletin board where people working on the project have listed problems. concerns, and challenges they’re facing and where they’re looking for help. + +Issues related to the Distribution Project fall into a few basic categories: Reviewing (packages, ), Developing, and Supplementing. +Some of the issues have little labels next to them that make me think of the brands on the flanks of my cattle. +These indicate the type of issue (e.g. “automation”) and the status (e.g. “Help Wanted”). + +.. image:: /_static/issues.png + +If you’re a greenhorn just starting out, look for issues that have a label like this: + +.. image:: /_static/good_first_issue.png + +If you see an issue you want to try and tackle you need to assign it to yourself as a first step. +To do that, click on the heading of that issue and a full profile of the issue you’re interested in will appear. +On the far right you’ll see a column of headings. +The first heading is “Assignee”. +The status under “Assignee” should read “No one assigned”. + +Click on the wheel symbol next to the word “Assignee” and a directory that lists the names of all the project’s participants will appear. +Scroll down to your name (the first name on the list, by default) and click on it. +A check mark will appear to the right of your name. +To confirm the assignment click on the wheel icon again and verify that your name now appears under the “Assignee” heading. +Congratulations! + +.. Attention:: If your name doesn’t appear on the drop-down list you will need to request access from either Vinoo Salvarajan or Jake Beal (sending a note via the Slack channel). + +So now its time to sign on to first project and get started. + + +(Illustrate using a real example here)