Note
We are currently reorganizing our repositories. We hope to complete work by the end of November 2014, but in the interim:
- Please check with us before creating pull requests against this repository --- we may point you at a new one.
- If you do create pull requests against this repository, please use the
gh-pagesbranch rather than themasterbranch.
Software Carpentry is an open source project, and we welcome contributions of all kinds: new and improved lessons, bug reports, and small fixes to existing material are all useful.
By contributing, you are agreeing that Software Carpentry may redistribute your work under these licenses.
Before beginning anything major, please read the README.md file in this directory, which explains how this repository is used to create websites for workshops. We also recommend that you look through open issues and pull requests to see what other people could use help with, and then open an issue of your own to get feedback on your ideas and coordinate with other developers.
Table of Contents
The following people are responsible for managing development of specific topics. They are not those lessons' primary authors; instead, their job is to make sure pull requests are reviewed, to decide whether and when to merge changes, and to decide what's in or out of scope for any topic. If a topic is maintained in an external repository, the topic name links to that repository.
- Bash: Gabriel Devenyi (@gdevenyi) and Christina Koch (@ChristinaLK)
- Git: Matt Davis (@jiffyclub) and Jessica Hamrick (@jhamrick)
- Python: Azalee Bostroem (@abostroem) and Trevor Bekolay (@tbekolay)
- SQL: Abigail Cabunoc (@acabunoc) and Sheldon McKay (@mckays630)
- R: John Blischak (@jdblischak) and Denis Haine (@dhaine)
- Mercurial: Doug Latornell (@douglatornell)
- MATLAB: Ashwin Srinath (@ashwinsrnth) and Isabell Kiral-Kornek (@IsaKiko)
- Build system: Raniere Silva (@r-gaia-cs) and Rémi Emonet (@twitwi)
- Windows installer: W. Trevor King (@wking) and Ethan White (@ethanwhite)
- Installation-test scripts: W. Trevor King (@wking)
In general, we are using Git and GitHub for almost everything. But if it is easier for you to send your contributions to us some other way, please mail us at [email protected]. Given a choice between you creating content or wrestling with Git, we'd rather have you doing the former.
Our GitHub workflow looks like this:
-
Fork the
swcarpentry/bcrepository on GitHub. -
Clone that repository to your own machine.
-
Create a branch from
gh-pagesfor your changes. Give your branch a meaningful name, such asfixing-typos-in-novice-shell-lessonoradding-tutorial-on-visualization. -
Make your changes, commit them, and push them to your repository on GitHub.
-
Send a pull request to the
gh-pagesbranch of[swcarpentry/bc](http://github.com/swcarpentry/bc).
Note: as noted at the top of this page,
please create pull requests against the gh-pages branch
rather than the master branch.
If it is easier for you to send them to us some other way, please mail us at [email protected]. Given a choice between you creating content or wrestling with Git, we'd rather have you doing the former.
Every subject has a sub-directory of its own,
while individual topics are files in that directory.
For example,
the novice/git directory holding our introduction to Git for newcomers
contains the files
00-intro.md,
01-backup.md,
and so on.
(We use two digits followed by a one-word topic key
to ensure files appear in the right order when listed.)
We are using Jekyll to convert lessons in Markdown to HTML. Therefore, we require every lesson to be available in Markdown. But this does not mean that you have to write it in Markdown as well.
The following list contains more detailed instructions for different formats:
- Markdown: Nothing to do.
- IPython Notebook: Generate and provide a Markdown version in addition to the IPython Notebook. Look at our existing files to get an idea how the IPython Notebook should look like.
- Other formats: Generate and provide a Markdown version in addition
to the file in the original format.
In order to be able to recreate the Markdown from source,
include the conversion from this other format to Markdown
in the
Makefileas well. This ensures that people who aren't familiar with some format don't have to install the tools needed to work with it (e.g., R programmers don't have to install the IPython Notebook). Please check with us if you plan to do this.
To preview changes before committing,
run the command make site.
This runs Jekyll with the same flags that GitHub uses when things are committed to the gh-pages branch
and puts the results in a directory called _site.
You should also run make check before pushing changes to your index.html home page
to your repository.
If you don't have Make installed,
you can run the same checks using:
python bin/swc_index_validator.py ./index.html
This checks that the workshop's instructors are listed, that a contact email address has been set up, and so on.
Other useful commands in the main Makefile are:
make commands(or justmakeon its own): list available commands.make clean: remove editor backup files and the_sitedirectory.make fixme: list uses of the wordFIXMEin source files.
The commands to convert IPython Notebooks to Markdown
are stored in a separate Makefile called ipynb.mk
to simplify maintenance
and ensure that the main Makefile only does what Jekyll on GitHub will do.
To re-do conversion of notebooks to Markdown files,
use make ipynb.
The directory misc contains files that can be used as starting points for lessons.
These files explain how to format titles,
objectives,
exercises,
key points,
and code fragments.
In addition,
the IPython Notebook file has metadata in various cells
to ensure that the generated HTML pages have the right style.
If you are creating a new lesson,
please copy one of these files to use as a starting point.
We use labels to categorize new Issues and Pull Requests. If you are searching for Issues to help resolve or Pull Requests to review, you can filter with these labels to help find subjects you are interested in. For example, if you are interested in improving the novice Python lessons, you can filter with the labels "Python" and "novice".
If you have "Contributor" status for swcarpentry/bc, please help organize
everything by adding informative labels to Issues and Pull Requests you create
as well as Issues and Pull Requests made by others.
See the list below for descriptions of some common labels:
- bug: something's wrong and needs to be fixed
- discussion: this issue is being used as a mini-mailing list to discuss something of specialized interest
- enhancement: identifies improvements to existing material (rather than bug fixes)
- getting-started: the task is suited for a newcomer, e.g. someone in instructor training
- intermediate: concerns the intermediate set of teaching material
- lessons: anything related to lessons that doesn't fit into a more specific category
- novice: concerns the novice set of teaching material
- question: asking for help or getting feedback on an idea
- tools: concerns the tools used to build and manage lesson material
- work in progress: the pull request is not ready to be merged
-
Where can I get help? Mail us at [email protected], come chat with us on our IRC channel, or join our discussion list and ask for help there.
-
Is there a list of open issues to tackle? The open issues for the bc repository and also the related projects listed on the create page are a good starting point.