Skip to content
This repository was archived by the owner on Aug 14, 2024. It is now read-only.

hard wrap at 79 characters #35

Merged
merged 8 commits into from
Feb 24, 2021
Merged

hard wrap at 79 characters #35

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ecc9f39
update scripts from upstream styles
tkphd Feb 20, 2021
3be6b29
hard wrap at 79 characters
tkphd Feb 20, 2021
492cbaa
apply codeblock types
tkphd Feb 20, 2021
83a8b56
bash -> language-bash
tkphd Feb 23, 2021
1f06058
wrap metadata
tkphd Feb 24, 2021
bbe9e35
can't begin a token with `
tkphd Feb 24, 2021
3a1500e
purge undefined codeblocks
tkphd Feb 24, 2021
b8920f7
missed a few wrappings
tkphd Feb 24, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 87 additions & 71 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,107 +1,123 @@
# Contributing

[Software Carpentry][swc-site] and [Data Carpentry][dc-site] are open source projects, and we
welcome contributions of all kinds: new lessons, fixes to existing material, bug reports, and
reviews of proposed changes are all welcome.
[Software Carpentry][swc-site] and [Data Carpentry][dc-site] are open source
projects, and we welcome contributions of all kinds: new lessons, fixes to
existing material, bug reports, and reviews of proposed changes are all
welcome.

## Contributor Agreement

By contributing, you agree that we may redistribute your work under [our license](LICENSE.md). In
exchange, we will address your issues and/or assess your change proposal as promptly as we can, and
help you become a member of our community. Everyone involved in [Software Carpentry][swc-site] and
[Data Carpentry][dc-site] agrees to abide by our [code of conduct](CODE_OF_CONDUCT.md).
By contributing, you agree that we may redistribute your work under [our
license](LICENSE.md). In exchange, we will address your issues and/or assess
your change proposal as promptly as we can, and help you become a member of our
community. Everyone involved in [Software Carpentry][swc-site] and [Data
Carpentry][dc-site] agrees to abide by our [code of
conduct](CODE_OF_CONDUCT.md).

## How to Contribute

The easiest way to get started is to file an issue to tell us about a spelling mistake, some awkward
wording, or a factual error. This is a good way to introduce yourself and to meet some of our
community members.
The easiest way to get started is to file an issue to tell us about a spelling
mistake, some awkward wording, or a factual error. This is a good way to
introduce yourself and to meet some of our community members.

1. If you do not have a [GitHub][github] account, you can [send us comments by email][email].
However, we will be able to respond more quickly if you use one of the other methods described
below.
1. If you do not have a [GitHub][github] account, you can [send us comments by
email][email]. However, we will be able to respond more quickly if you use
one of the other methods described below.

2. If you have a [GitHub][github] account, or are willing to [create one][github-join], but do not
know how to use Git, you can report problems or suggest improvements by
[creating an issue][issues]. This allows us to assign the item to someone and to respond to it
in a threaded discussion.
2. If you have a [GitHub][github] account, or are willing to [create
one][github-join], but do not know how to use Git, you can report problems
or suggest improvements by [creating an issue][issues]. This allows us to
assign the item to someone and to respond to it in a threaded discussion.

3. If you are comfortable with Git, and would like to add or change material, you can submit a pull
request (PR). Instructions for doing this are [included below](#using-github).
3. If you are comfortable with Git, and would like to add or change material,
you can submit a pull request (PR). Instructions for doing this are
[included below](#using-github).

## Where to Contribute

1. If you wish to change this lesson, please work in <https://github.com/swcarpentry/FIXME>, which
can be viewed at <https://swcarpentry.github.io/FIXME>.
1. If you wish to change this lesson, please work in
<https://github.com/swcarpentry/FIXME>, which can be viewed at
<https://swcarpentry.github.io/FIXME>.

2. If you wish to change the example lesson, please work in
<https://github.com/carpentries/lesson-example>, which documents the format of our lessons and
can be viewed at <https://carpentries.github.io/lesson-example>.
2. If you wish to change the example lesson, please work in
<https://github.com/carpentries/lesson-example>, which documents the format
of our lessons and can be viewed at
<https://carpentries.github.io/lesson-example>.

3. If you wish to change the template used for workshop websites, please work in
<https://github.com/carpentries/workshop-template>. The home page of that repository explains
how to set up workshop websites, while the extra pages in
<https://carpentries.github.io/workshop-template> provide more background on our design choices.
3. If you wish to change the template used for workshop websites, please work
in <https://github.com/carpentries/workshop-template>. The home page of that
repository explains how to set up workshop websites, while the extra pages
in <https://carpentries.github.io/workshop-template> provide more background
on our design choices.

4. If you wish to change CSS style files, tools, or HTML boilerplate for lessons or workshops
stored in `_includes` or `_layouts`, please work in <https://github.com/carpentries/styles>.
4. If you wish to change CSS style files, tools, or HTML boilerplate for
lessons or workshops stored in `_includes` or `_layouts`, please work in
<https://github.com/carpentries/styles>.

## What to Contribute

There are many ways to contribute, from writing new exercises and improving existing ones to
updating or filling in the documentation and submitting [bug reports][issues] about things that
don't work, aren't clear, or are missing. If you are looking for ideas, please see the 'Issues' tab
for a list of issues associated with this repository, or you may also look at the issues for
[Data Carpentry][dc-issues] and [Software Carpentry][swc-issues] projects.
There are many ways to contribute, from writing new exercises and improving
existing ones to updating or filling in the documentation and submitting [bug
reports][issues] about things that don't work, aren't clear, or are missing. If
you are looking for ideas, please see the 'Issues' tab for a list of issues
associated with this repository, or you may also look at the issues for [Data
Carpentry][dc-issues] and [Software Carpentry][swc-issues] projects.

Comments on issues and reviews of pull requests are just as welcome: we are smarter together than we
are on our own. Reviews from novices and newcomers are particularly valuable: it's easy for people
who have been using these lessons for a while to forget how impenetrable some of this material can
be, so fresh eyes are always welcome.
Comments on issues and reviews of pull requests are just as welcome: we are
smarter together than we are on our own. Reviews from novices and newcomers are
particularly valuable: it's easy for people who have been using these lessons
for a while to forget how impenetrable some of this material can be, so fresh
eyes are always welcome.

## What *Not* to Contribute

Our lessons already contain more material than we can cover in a typical workshop, so we are usually
*not* looking for more concepts or tools to add to them. As a rule, if you want to introduce a new
idea, you must (a) estimate how long it will take to teach and (b) explain what you would take out
to make room for it. The first encourages contributors to be honest about requirements; the second,
to think hard about priorities.
Our lessons already contain more material than we can cover in a typical
workshop, so we are usually *not* looking for more concepts or tools to add to
them. As a rule, if you want to introduce a new idea, you must (a) estimate how
long it will take to teach and (b) explain what you would take out to make room
for it. The first encourages contributors to be honest about requirements; the
second, to think hard about priorities.

We are also not looking for exercises or other material that only run on one platform. Our workshops
typically contain a mixture of Windows, macOS, and Linux users; in order to be usable, our lessons
must run equally well on all three.
We are also not looking for exercises or other material that only run on one
platform. Our workshops typically contain a mixture of Windows, macOS, and
Linux users; in order to be usable, our lessons must run equally well on all
three.

## Using GitHub

If you choose to contribute via GitHub, you may want to look at
[How to Contribute to an Open Source Project on GitHub][how-contribute]. To manage changes, we
follow [GitHub flow][github-flow]. Each lesson has two maintainers who review issues and pull
requests or encourage others to do so. The maintainers are community volunteers and have final say
over what gets merged into the lesson. To use the web interface for contributing to a lesson:

1. Fork the originating repository to your GitHub profile.
2. Within your version of the forked repository, move to the `gh-pages` branch and create a new
branch for each significant change being made.
3. Navigate to the file(s) you wish to change within the new branches and make revisions as
required.
4. Commit all changed files within the appropriate branches.
5. Create individual pull requests from each of your changed branches
If you choose to contribute via GitHub, you may want to look at [How to
Contribute to an Open Source Project on GitHub][how-contribute]. To manage
changes, we follow [GitHub flow][github-flow]. Each lesson has two maintainers
who review issues and pull requests or encourage others to do so. The
maintainers are community volunteers and have final say over what gets merged
into the lesson. To use the web interface for contributing to a lesson:

1. Fork the originating repository to your GitHub profile.
2. Within your version of the forked repository, move to the `gh-pages` branch
and create a new branch for each significant change being made.
3. Navigate to the file(s) you wish to change within the new branches and make
revisions as required.
4. Commit all changed files within the appropriate branches.
5. Create individual pull requests from each of your changed branches
to the `gh-pages` branch within the originating repository.
6. If you receive feedback, make changes using your issue-specific branches of the forked
repository and the pull requests will update automatically.
7. Repeat as needed until all feedback has been addressed.
6. If you receive feedback, make changes using your issue-specific branches of
the forked repository and the pull requests will update automatically.
7. Repeat as needed until all feedback has been addressed.

When starting work, please make sure your clone of the originating `gh-pages` branch is up-to-date
before creating your own revision-specific branch(es) from there. Additionally, please only work
from your newly-created branch(es) and *not* your clone of the originating `gh-pages` branch.
Lastly, published copies of all the lessons are available in the `gh-pages` branch of the
originating repository for reference while revising.
When starting work, please make sure your clone of the originating `gh-pages`
branch is up-to-date before creating your own revision-specific branch(es) from
there. Additionally, please only work from your newly-created branch(es) and
*not* your clone of the originating `gh-pages` branch. Lastly, published copies
of all the lessons are available in the `gh-pages` branch of the originating
repository for reference while revising.

## Other Resources

General discussion of [Software Carpentry][swc-site] and [Data Carpentry][dc-site] happens on the
[discussion mailing list][discuss-list], which everyone is welcome to join. You can also
[reach us by email][email].
General discussion of [Software Carpentry][swc-site] and [Data
Carpentry][dc-site] happens on the [discussion mailing list][discuss-list],
which everyone is welcome to join. You can also [reach us by email][email].

<!-- References -->

[email]: mailto:admin@software-carpentry.org
[dc-issues]: https://github.com/issues?q=user%3Adatacarpentry
Expand Down
1 change: 1 addition & 0 deletions Gemfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins
gem "kramdown-parser-gfm"
100 changes: 54 additions & 46 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,73 +1,81 @@
# Introduction to using the shell in a High-Performance Computing context

This lesson provides an introduction to the bash shell aimed at researchers who will be using
the command line to use remote, high-performance computing (HPC) systems. The material is also
suitable for teaching the use of the shell for any remote, advanced computing resources.
This lesson provides an introduction to the bash shell aimed at researchers who
will be using the command line to use remote, high-performance computing (HPC)
systems. The material is also suitable for teaching the use of the shell for
any remote, advanced computing resources.


## Using this material

1. Follow the instructions found in the [Software Carpentry example lesson source](https://github.com/carpentries/lesson-example/)
to create a repository for your lesson.
2. Edit [_config.yml](_config.yml) to modify the configuration options at the bottom for the
remote host you will be using. These options set such things as the address of the host
to login to and the ID that is used to incorporate host-specific code snippets (see below).
1. Follow the instructions found in the [Software Carpentry example lesson
source](https://github.com/carpentries/lesson-example/) to create a
repository for your lesson.
2. Edit [_config.yml](_config.yml) to modify the configuration options at the
bottom for the remote host you will be using. These options set such things
as the address of the host to login to and the ID that is used to
incorporate host-specific code snippets (see below).
3. Create the required host-specific code snippets in subdirectories in
[_includes/snippets](_includes/snippets). These snippets provide inputs and outputs that
are host-specific and that are included automatically based on the configuration in the
`_config.yml` file.
1. Code snippets are in files named `snippet_name.host_id` and are included automatically
when the lesson is built. For example, if the `snippet_name` was `login_output` and the
`host_id` was `ComputeCanada_Graham`, then the snippet file would be called
`login_output.ComputeCanada_Graham`.
2. Code snippets are placed in subdirectories that are named according to the episode they
appear in. For example, if the snippet is for episode 01, then it will be in a
subdirectory called `01`.
[_includes/snippets](_includes/snippets). These snippets provide inputs and
outputs that are host-specific and that are included automatically based on
the configuration in the `_config.yml` file.
1. Code snippets are in files named `snippet_name.host_id` and are included
automatically when the lesson is built. For example, if the
`snippet_name` was `login_output` and the `host_id` was
`ComputeCanada_Graham`, then the snippet file would be called
`login_output.ComputeCanada_Graham`.
2. Code snippets are placed in subdirectories that are named according to
the episode they appear in. For example, if the snippet is for episode
01, then it will be in a subdirectory called `01`.


## Lesson writing instructions

This is a fast overview of the Software Carpentry lesson template. This won't cover lesson style or
formatting (address that during review?).
This is a fast overview of the Software Carpentry lesson template. This won't
cover lesson style or formatting (address that during review?).

For a full guide to the lesson template, see the
[Software Carpentry example lesson](http://swcarpentry.github.io/lesson-example/).
For a full guide to the lesson template, see the [Software Carpentry example
lesson](http://swcarpentry.github.io/lesson-example/).

### Lesson structure

Software Carpentry lessons are generally episodic, with one clear concept for each episode
([example](http://swcarpentry.github.io/r-novice-gapminder/)).
Software Carpentry lessons are generally episodic, with one clear concept for
each episode ([example](http://swcarpentry.github.io/r-novice-gapminder/)).

An episode is a markdown file that lives under the `_episodes` folder. Here is a link to a
[markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) with most
markdown syntax. Additionally, the Software Carpentry lesson template uses several extra bits of
formatting- see here for a [full guide](http://swcarpentry.github.io/lesson-example/04-formatting/).
The most significant change is the addition of a YAML header that adds metadata (key questions,
lesson teaching times, etc.) and special syntax for code blocks, exercises, and the like.
An episode is a markdown file that lives under the `_episodes` folder. Here is
a link to a [markdown
cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
with most markdown syntax. Additionally, the Software Carpentry lesson template
uses several extra bits of formatting- see here for a [full
guide](http://swcarpentry.github.io/lesson-example/04-formatting/). The most
significant change is the addition of a YAML header that adds metadata (key
questions, lesson teaching times, etc.) and special syntax for code blocks,
exercises, and the like.

Episode names should be prefixed with a number of their section plus the number of their episode
within that section. This is important because the Software Carpentry lesson template will auto-post
our lessons in the order that they would sort in. As long as your lesson sorts into the correct
order, it will appear in the correct order on the website.
Episode names should be prefixed with a number of their section plus the number
of their episode within that section. This is important because the Software
Carpentry lesson template will auto-post our lessons in the order that they
would sort in. As long as your lesson sorts into the correct order, it will
appear in the correct order on the website.

### Publishing changes to Github + the Github pages website
### Publishing changes to GitHub + the GitHub pages website

The lesson website is viewable at
[https://hpc-carpentry.github.io/hpc-shell/](https://hpc-carpentry.github.io/hpc-shell/)
The lesson website is viewable at <https://hpc-carpentry.github.io/hpc-shell/>.

The lesson website itself is auto-generated from the `gh-pages` branch of this repository. Github
pages will rebuild the website as soon as you push to the Github `gh-pages` branch. Because of this
`gh-pages` is considered the "master" branch.
The lesson website itself is auto-generated from the `gh-pages` branch of this
repository. GitHub pages will rebuild the website as soon as you push to the
GitHub `gh-pages` branch. Because of this `gh-pages` is considered the "master"
branch.

### Previewing changes locally

Obviously having to push to Github every time you want to view your changes to the website isn't
very convenient. To preview the lesson locally, run `make serve`. You can then view the website at
`localhost:4000` in your browser. Pages will be automatically regenerated every time you write to
them.
Obviously having to push to GitHub every time you want to view your changes to
the website isn't very convenient. To preview the lesson locally, run `make
serve`. You can then view the website at `localhost:4000` in your browser.
Pages will be automatically regenerated every time you write to them.

Note that the autogenerated website lives under the `_site` directory (and doesn't get pushed to
Github).
Note that the autogenerated website lives under the `_site` directory (and
doesn't get pushed to GitHub).

This process requires Ruby, Make, and Jekyll. You can find setup instructions
[here](http://swcarpentry.github.io/lesson-example/setup/).
Expand Down
Loading