For the "by hand" instructions I see a warning at step 2: warning: You appear to have cloned an empty repository.. I wonder if it is worth noting that this is expected and not a problem.

When testing out the "by hand" instructions I ran into a problem with step 6. With my setup this gives the error fatal: You are on a branch yet to be born. This may be due to my (quite old) git install (version 1.7.3.4). A work around is to run git pull upstream gh-pages:gh-pages; git checkout gh-pages instead (replacing step 6 and 7).

The following section need instructions on how to commit in addtion to push

1. Commit your changes and push to the gh-pages branch of your repository using
   $ git push origin gh-pages

Here's a suggestions
$ git commit -a

check.py:

• doesn't think European-ordered dates such as 15 Nov 2015 are human readable. Also, the human-readable option seems like a natural candidate for just using a Jekyll Liquid filter {{ startdate | date: %b %d %Y}} as an easy way to enforce a particular format... (yes, ranges get more tricky if they are split over months, or if no end-date is supplied...)
• doesn't recognize the alternate but cleaner yaml list syntax using - to make a list instead of ["item 1", "item 2"] (in listing instructors and users).

in the customization.md file, there's a word missing

"root must the path"

http://files.software-carpentry.org/create does not exist.

Make it so that people can directly copy and paste the bash commands from the text box. The '$' is still a useful placeholder, so place it to the left of the box.

When the workshop setup script is downloaded on a Mac, it may save as .txt instead of .sh - document so that people aren't confused.

tools/create is supposed to give zero or more people permission to push changes to the repo it's creating, but doesn't appear to do that.

YAML header are of the form

---
key1: value1
key2: value 2

---

Users can break YAML header by accident. E.g. having

---
key1: value1
key2: value2
--> ---

tools/check.py don't detect this:

$ tools/check.py 
Testing "./index.html".
Traceback (most recent call last):
  File "tools/check.py", line 272, in <module>
    is_valid = check_file(index_fh)
  File "tools/check.py", line 224, in check_file
    header_data, seen_categories = get_header(index_fh)
  File "tools/check.py", line 218, in get_header
    return yaml.load("\n".join(header)), this_categories
  File "/usr/local/lib/python2.7/dist-packages/yaml/__init__.py", line 71, in load
    return loader.get_single_data()
  File "/usr/local/lib/python2.7/dist-packages/yaml/constructor.py", line 37, in get_single_data
    node = self.get_single_node()
  File "/usr/local/lib/python2.7/dist-packages/yaml/composer.py", line 36, in get_single_node
    document = self.compose_document()
  File "/usr/local/lib/python2.7/dist-packages/yaml/composer.py", line 55, in compose_document
    node = self.compose_node(None, None)
  File "/usr/local/lib/python2.7/dist-packages/yaml/composer.py", line 84, in compose_node
    node = self.compose_mapping_node(anchor)
  File "/usr/local/lib/python2.7/dist-packages/yaml/composer.py", line 133, in compose_mapping_node
    item_value = self.compose_node(node, item_key)
  File "/usr/local/lib/python2.7/dist-packages/yaml/composer.py", line 64, in compose_node
    if self.check_event(AliasEvent):
  File "/usr/local/lib/python2.7/dist-packages/yaml/parser.py", line 98, in check_event
    self.current_event = self.state()
  File "/usr/local/lib/python2.7/dist-packages/yaml/parser.py", line 449, in parse_block_mapping_value
    if not self.check_token(KeyToken, ValueToken, BlockEndToken):
  File "/usr/local/lib/python2.7/dist-packages/yaml/scanner.py", line 115, in check_token
    while self.need_more_tokens():
  File "/usr/local/lib/python2.7/dist-packages/yaml/scanner.py", line 149, in need_more_tokens
    self.stale_possible_simple_keys()
  File "/usr/local/lib/python2.7/dist-packages/yaml/scanner.py", line 289, in stale_possible_simple_keys
    "could not found expected ':'", self.get_mark())
yaml.scanner.ScannerError: while scanning a simple key
  in "<string>", line 16, column 1:
    --> ---
    ^
could not found expected ':'
  in "<string>", line 17, column 1:
    <!--
    ^

It would be nice to be able to tag issues as 'bite-size' to encourage participation by new contributors to this project or contributions by interested folks that are short on time.

Small contribution tasks are a great way to build community and participation ☀️

If someone with the correct permissions to add a label to this repo could do so, that would be great.

In running the create script

 ./workshop-create 2014-11-15-boettiger "Boettiger's workshop" cboettig gvwilson

I'm asked for my Github password, after which I immediately get the error:

HTTP/1.1 301 Moved Permanently
ERROR: this repository already exists

My requested repository does not already exist

I think there's several problems going on here.

• If I intentionally provide an incorrect password I still get this same error message, instead of a "password incorrect" error.
• I believe my Github credentials are configured such that one would need two-factor authentication, ssh key, or personal token to perform tasks, so I suspect that when I provide the correct password I'm still getting an authentication error.

General feedback: I found the manual instructions more intuitive

Nothing in the docs say 'chmod +x' after downloading - say that, or tell people to run with 'bash swc-workshop-setup'.

The automated setup script tools/create should erase FAQ.md, DESIGN.md, and CUSTOMIZATION.md (since workshop websites don't need them), and overwrite README.md with something very simple (since workshop websites don't need setup instructions). The manual setup instructions should tell people to do this too.

In swcarpentry/DEPRECATED-bc#527 we discuss to request students to install a merge tool.

Should we preserve the history when copying files from swcarpentry/bc?

I've just gone through the process of creating a bootcamp website as described in this repo. The site passes tools/check.py and renders correctly when I run tools/preview. However, once pushed to github, none of the images render and styles are not applied to the site. Both Chrome and Firefox tell me that the page is insecure, and I have to allow the unsecure parts of the page for it to correctly render.

Has anyone else seen this occur before? Is it a problem with my index.html? If so, can we add the appropriate tests to tools/check.py?

Here is the site:
https://resbaz.github.io/2014-12-08-combine-r/

And the corresponding index.html:
https://github.com/resbaz/2014-12-08-combine-r/blob/gh-pages/index.html

We decided to put shell scripts in the tools directory, and have people invoke them by name, to do common tasks so that people wouldn't need to install make. This is inconsistent with both the lesson template and the main website, and since we're hoping instructors will frequently update lessons, it seems silly to have different tooling for workshops. I therefore propose that we create a Makefile similar to the one in the lesson-template directory to drive common operations.

I had a go at creating a website for a workshop I'm running next year:
http://damienirving.github.io/2015-07-13-amos/

As you'll see at that link, the site looks very plain and it's missing the header information (e.g. SWC logo, location, date, time, instructors, etc).

in tools/create, the return codes are being tested in differnt ways:

if [[ -eq 0 ]]  

versus

if test ... -ne 1)

I've got a PR that standardizes them. While I was at it, I wrote an additional script to test the simpler helper functions in tools/create that works nicely, but requires the helper functions to send SIGINT explicitly with kill, rather than using exit 2 (which cannot be trapped):

function check_pwd {
    success=$(git status > /dev/null 2>&1; echo $?)
    if test ${success} -eq 0
    then
        echo "ERROR: you are already inside a Git repository."
        kill -2 $$
    fi
}

function test_check_pwd {
    PWD=`pwd`
    echo "expecting ERROR run in $PWD ..."
    trap '' 2
    check_pwd
    trap - 2
}

# Main driver.
function tests {
    test_check_pwd
}

tests

Anyone object to using using kill vs exit? If not, I'll send my PR along with the test script. Otherwise, I'll just send my PR without the test, where the functions use exit when the detect an error.

At least on my computer (with Ubuntu 14.10), to run test/check.py I needed to install the yaml python module. Should this dependency be included in the README?

@benwaugh has an excellent overview of the issues with HTTPS and older versions of git. It was originally presented in PR #37. It is moved here for solution.

When pushing to a GitHub repository using HTTPS, there are problems if using a slightly older version of Git, in that it does not prompt for a username and password when you try to push to the remote but just reports a 403 access error. This is fixed in Git 1.9.3 but doesn't work in Git 1.7.1, which is the default on RHEL 6. I haven't checked any intermediate versions.

There is a workaround, which is to change the URL from https://github.com/ghopper/2015-07-01-esu.git to https://[email protected]/ghopper/2015-07-01-esu.git but this is more complex in that:

• you can't just copy and paste the URL from the GitHub page
• there are two different usernames in the URL when you are directly cloning from someone else's repository (although this is not the case here)

How can we help anyone who has this problem without overcomplicating the "happy path" instructions?

• add in the username to the URL here, even though it is not necessary with newer versions of Git
• add a troubleshooting section to the instructions
• list a recent version of Git as a dependency (may not be easily available to everyone)
• leave everything as is and resolve problems on the mailing list (but some organizers may waste time before asking for help, even if they eventually do so)

When executing the example found in tools/create, a command not found error is generated and references line 136.

This is the test example:
tools/create 2015-06-18-esu "Euphoric State University" aturing ghopper

Following the instructions for building by hand, both git clone [email protected]:/ghopper/2015-07-01-esu (which is suggested in the instructions) and git clone [email protected]:ghopper/2015-07-01-esu.git (which is what you'd cut and past from GitHub) produce the following error for me:

Cloning into '2015-07-01-esu'...
Warning: Permanently added the RSA host key for IP address '192.30.252.129' to the list of known hosts.
Permission denied (publickey).
fatal: Could not read from remote repository.

The https cloning worked fine for me (git clone https://github.com/ghopper/2015-07-01-esu.git), so perhaps the instructions should just suggest the https cloning instead?

I also had the same kinds of failures when setting the remote using the ssh method (git remote add upstream [email protected]:swcarpentry/workshop-template) but it worked fine using the https method, so perhaps this should be changed in the instructions too?

Instead of ghopper (which is easy to overlook), change the example to e.g. YOURUSERNAME, [USERNAME], etc

in readme.md

I notice the current template organizes installation instructions by software (separate sections for Bash, git, Python, R, SQLite) rather than by platform as used to be the case. What was the reason for the change?

My knee-jerk reaction is that organizing by platform was much more useful to students, because at least some of them are not going to know what "git" is until after the workshop, and most people know whether they have Windows, Linux, or Mac OS X.

Need to create a README so that the repository is immediately clonable without warnings, but we'll provide the license.

It would be helpful for the workshop organizer to be able to simply set up a repo for student access. An automated script could be a useful tool.

It may be possible to use the github3.py library (http://github3py.readthedocs.org/en/latest/) to simplify some of the scripting.

• step 6 should be listed as optional because you may not have all the software installed
• in step 7 you should have the commit command explicitly listed and not repeat the push command
• in step 6 a hyper link to the dependency installation procedure would be useful

The other Trevor seems to have taken down his repository, but mine is still up. I'd expect wking/swc-template@7d018ccab (LICENSE.md: Bump the CC BY 3.0 to 4.0, 2014-10-22) would apply cleanly to anyone using the stock SWC LICENSE.md. My commit message lists the titles from the v4 release notes, for folks who are wondering “why bump?”

Following discussion in #92, can be adapted from the CONTRIBUTING.md in swcarpentry/bc

In the setup instructions for participants (in index.html) we do not currently say that people will need a web browser. This is probably fine as everybody will have one. However, the requirements for accessing github are not totally trivial (e.g. see this https://github.com/blog/1937-improving-github-s-ssl-setup). I wonder if it's worth including a line pointing at this: https://help.github.com/articles/supported-browsers/. Maybe insert something like the following at the start of the setup section?

To participate in a Software Carpentry workshop, you will need access to the software described
below. In addition, you will need a web browser 
<a href='https://help.github.com/articles/supported-browsers/'>able to access github.com</a>.
Please make sure to install everything (or at least to download the installers) before the start 
of your workshop. <a href="setup/index.html">This page</a> has instructions on testing
that you have the right software installed.

Or maybe not? I've never actually seen a problem with this in a workshop.

It may be worthwhile to put in what versions of Ruby are required, especially if Ruby isn't used often by the person setting up the workshop. So systems may not be supported - maybe detail what version of Ruby is the minimum support (1.9.3 seems to be the minimum).

When attempting to test #84, I tried to download the script from the link in the instructions.
http://files.software-carpentry.org/workshop-create

Received the following 404 error:
The requested URL /workshop-create was not found on this server.
Additionally, a 404 Not Found error was encountered while trying to use an ErrorDocument to handle the request.

Perhaps this is due to PR #90.

In tools/create

git clone -b gh-pages -o upstream \
        https://github.com/${WORKSHOP_TEMPLATE_SRC}.git ${REPOSITORY_PATH}
    if test $? -eq 0
    then
        cd ${REPOSITORY_PATH}
            ${WORKSHOP_URL/https:\/\//https:\/\/${OWNER}@}.git
        git remote add origin \
        git config credential.username ${OWNER}
        git push -u origin gh-pages

git remote -v

gdevenyi@titan ~/Documents/2014-11-16-test $ git remote -v
upstream    https://github.com/swcarpentry/workshop-template.git (fetch)
upstream    https://github.com/swcarpentry/workshop-template.git (push)

Only has upstream listed.

The clone_and_push function in tools/create doesn't check that the repository was successfully cloned before trying to cd into it. It should.

When we tried to git remote add origin ... got error fatal remote origin already exists.

This worked: git remote set-url origin ...

Add a new section after Getting Help that would highlight the last sentence regarding filing issues and improvement. Perhaps something similar to:

Sharing your experience
We are committed to providing our users a pleasant workshop set up experience. If you have noticed a place where we could improve the set up experience for future workshop organizers, please share your thoughts by filing an issue or email us.

Thank you for organizing a workshop. Best wishes for your upcoming workshop from all of us at Software Carpentry.

As a result of discussion on issue #65, it is helpful to provide meaningful, detailed messages to the user when errors are displayed.

The messages should be helpful to a user with command line and bash experience (i.e. setting paths and environment variables) yet may not be proficient with bash scripting.

tools/create should check that the repository it's about to create doesn't already exist on GitHub before doing anything further. #16 addresses this.

Steps 1 to 5 in the Semi Automated Setup section of README.md should be more user friendly and be consistent on script name workshop-create or create.

As the workshop-create script has improved over the past couple of weeks, the Semi Automated Setup instructions should be revised to reflect actual user experience.

Below are examples of the current user experience on a Mac using OS X 10.9.

Step 1

• If the link is clicked it opens the file in a browser window.
• At this point, a user would have one of two options: a) cut and paste the text into a new file with workshop-create name or b) go back a page in the browser and then click link again while holding down the option key.
• Once having the file by either method, the user will need to make the text file executable by changing the file permissions.

Ideally, clicking the link would download the file to the Mac.

Step 2

The script now checks if the directory is in a git repo.
Is Step 2 still necessary? If so, instruct user on how to check via git status as the script or git rev-parse --git-dir. If not, consider combining with Step 3.

Step 3

Run workshop-create -h to display parameters needed for Step 4.

Step 4

Run workshop-create with the desired workshop parameters. As an example, tools/create 2015-06-18-esu "Euphoric State University" aturing ghopper.

Note: The user has been using workshop-create as the script name which does not match the naming in the script's help which uses create.

Step 5

Minor edit for clarity; suggest "Change directory into the newly created workshop repository directory.

I think all the info on how to build the site locally (i.e. installing Ruby, Jekyll etc) is going to scare a lot of people off. I think it should be stressed up front that the ability to build locally is not critical to creating a website. In reality, most people (i.e. those that have an internet connection) are just going to push changes to their repo on GitHub and then navigate to the website (http://ghopper.github.io/2015-07-01-esu/) to see if the changes look like they expected (or at least that's the way I do it).

i.e., not 2015-01-01-EuphoricStateUniversity or anything like that.

The installation checking scripts in the setup directory currently point people at http://software-carpentry.org/setup/ when things go wrong. They should point at the particular workshop's website instead, but we can't (easily) inject that URL into the scripts (which will be downloaded and run on the learners' machines).

See #83 for some discussion.

A CONTRIBUTING.md file is a good place to put style and conduct recommendations for contributors. The bc repo has one that might be useful as a template.

Opened per discussion in #92,

The validator should check the country names in the header against a list, so that people don't try to create workshops with countries like 'US' or 'United States' (it has to be hyphenated as 'United-States' in order to match the names of flags in the final website).

tools/create in workshop_template uses a mix of styles for checking the status of shell commands:

success=$(some command; echo $?)
if [[ ${success} -eq 0 ]];
then
    ...error message and exit...
fi

versus

some command
if test $? -ne 1
then
    ...error message and exit...
fi

We should settle on one or the other...

As a result of discussion in #65, adding tests to the tools/create are an enhancement to the script. The tests should be added as needed and based on feedback from users (especially the first few groups to use this version of the workshop-template).

Trying to run tools/create inside a Git repo (like this one) is a common mistake. The code in the shell script to check for this runs the right test, but isn't checking the return value properly.