Skip to content

Commit

Permalink
Merge pull request #314 from csc-training/contributing-updates
Browse files Browse the repository at this point in the history 
update contributing
  • Loading branch information
@rkronberg
rkronberg authored Feb 2, 2024
2 parents f034ff1 + 25138a6 commit 9e4aa5d
Show file tree
Hide file tree
Showing 5 changed files with 255 additions and 173 deletions.
157 changes: 92 additions & 65 deletions _contributing/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,80 +4,107 @@

CSC staff: do these two things _first_:

1. Join the Git organization [csc-training](https://github.com/csc-training) by sending email to [email protected].
2. Then [join here the CSC employees team](https://github.com/orgs/CSCfi/teams/employees/members). Membership
gives you permissions to edit source files that build the content. (Wait for a confirmation email.)
1. Join the GitHub organization [csc-training](https://github.com/csc-training)
by sending email to <mailto:[email protected]>.
2. Then [join CSC employees team](https://github.com/orgs/CSCfi/teams/employees/members).
Membership gives you permissions to edit the source files that build the
content (wait for a confirmation email).

The rest of this document describes the workflow in Github as
well as instructions for previewing and deploying the documentation.
See [Style guide](STYLEGUIDE.md) for content and formatting instructions.
The rest of this document describes the workflow in GitHub as well as
instructions for previewing and deploying the documentation. See the
[style guide](STYLEGUIDE.md) for content and formatting instructions.

## For the impatient (Note: this will differ for CSC Staff and non-staff)
## For the impatient (note: this will differ for CSC Staff and non-staff)

Once you've completed the steps above:
* (sign in GitHub) and edit then content
* Scroll down to commit changes (create a new branch, don't push directly to master) -> make a pull request
* Assign a reviewer or merge yourself if it's a small thing

* (Sign in to GitHub) and edit the content.
* Scroll down to commit changes, create a new branch (don't push directly to
master) and then make a pull request (PR).
* Assign a reviewer or merge yourself if it's just a small thing.

## Making changes using pull requests

The csc-env-eff repository uses the 'master' as the default
branch. You can make changes in web gui, command line or desktop application.
The csc-env-eff repository uses 'master' as the default branch. You can make
changes using the web GUI, command-line or desktop application.

Master branch is not protected. You can make changes to it directly, but please
don't. Instead, make a "feature branch" for your change and then create a pull request.
The master branch is not protected. You can make changes to it directly,
**but please don't**. Instead, make a "feature branch" for your change and then
create a pull request.

### Overview
**writer:**

- Create your own branch from master (or work in an already existing branch, if agreed)
- Create / bring there the content you want to work with. Pay attention to file naming!
- When creating a new exercise / tutorial add it to it's subfolder's README.md
- Make a pull request for your work to be added to Master
- Assign a reviewer if you want
- **Tip** Add a link to the html-page ([see instructions for publishing the slides in Allas](MD_into_html.md/#publish-html-files-in-allas) )
- Write meaningful pull request messages, so it is easier for reviewers to do their job.
- Communicate! Use "WIP" (= Work In Progress) in your pull request title, if you don't wish the branch to be merged to master (i.e. you want to continue working with it).
- You can also merge the branch yourself, but please delete the feature branch afterwards, if you no longer use it

**Reviewer:** If you get a request to review a pull request, please contribute to help publish the changes!

- Edit the pages as needed (perhaps via the Web GUI)
- It's ok to edit typos directly in the text
- **Pro tip**
- Suggest changes so that they appear as `diff` in the conversation tab, so that the author can simply commit/reject them
- In the "Files changed" tab, scroll to the line you want to change and press the blue "+" at the start of the line
- In the appearing pop-up, press the sim-card-look-a-like icon with + and - on top of each other
- write between the tics (including the suggestion) what you want to appear in the page
- If you want to remove a line, delete the content (and leave the tics and the word suggestion)
- If you want to remove lines, write the preceding and trailing lines
- Write a comment outside the tics, if you want, and use Preview to see the resulting `diff`
- Press "Add Single Comment"
- Once you're happy with the content, in the "Files changed" tab click "Review changes" -> "Approve"
- Anyone can be a reviewer


### Making pull requests in the web GUI

#### Writer:

- Create your own branch from master (or work in an already existing branch, if
agreed).
- Create/bring there the content you want to work with. Pay attention to file
naming! Avoid overly complicated/long filenames.
- Create a pull request for your work to be added to master
- Assign a reviewer if you want.
- **Tip:** If editing slides, add a link to the HTML-page
([see instructions for publishing slides in Allas](MD_INTO_HTML.md/#publish-html-files-in-allas)).
- Write meaningful commit messages, so it's easier for reviewers to do
their job.
- Communicate! Use 'WIP' (= Work In Progress) in your PR title if you don't
wish the branch to be merged to master (i.e. you want to continue working
with it).
- You can also merge the branch yourself, but please delete the feature branch
afterwards.

#### Reviewer:

If you get a request to review a PR, please contribute to help publish the
changes!

- Edit the pages as needed (perhaps via the web GUI).
- It's ok to edit typos directly in the text.
- **Tip:**
- Suggest changes so that they appear as a `diff` in the conversation tab,
so that the author can simply commit/reject them.
- In the 'Files changed' tab, scroll to the line you want to change and
press the blue '+' at the start of the line.
- In the appearing pop-up, press the sim-card-look-a-like icon with + and -
on top of each other.
- Write between the ticks (including the suggestion) what you want to
appear in the page.
- If you want to remove a line, delete the content (leave the ticks and
the word 'suggestion').
- If you want to remove lines, write the preceding and trailing lines.
- Write a comment outside the ticks, if you want, and use 'Preview' to see
the resulting `diff`.
- Press 'Add Single Comment'.
- Once you're happy with the content, in the 'Files changed' tab, click 'Review
changes' and select 'Approve'.
- Anyone can be a reviewer.

### Making pull requests using the web GUI

In the master branch, navigate to the page you want to edit, click the pen-logo
at the top right and once ready, at the bottom choose "Create new branch from this
commit and start a pull request". Note, that you can give the branch a descriptive
name at this point. If you wish to edit an already existing branch, first change to
the correct branch in the "branch" button on upper left, next to the path to the
file. If you found an error in the pull request of your own branch, you should commit
to it directly instead of creating another pull request (the two choices at the bottom).

### Making pull requests on the command line

Overview:

- Clone the reposity (if not done already) `git clone https://github.com/csc-training/csc-env-eff.git`
- Change to master branch (if not already) `git checkout master`
- Update local repository `git pull`
- Make a new branch from the master branch `git checkout -b my-new-branch`
- Create content and `add` edited files in your new branch `emacs ...; git add file`
- Commit your changes `git commit -m 'short description'`
- Check status (all files committed etc.) `git status`
- Push changes to github `git push origin my-new-branch`
- Make a pull request to merge changes from your new branch into the develop branch (in the web guide)
- Ask a person to review and merge the changes
at the top right and once ready, at the bottom, choose 'Create new branch from
this commit and start a pull request'. Note that you can give the branch a
descriptive name at this point. If you wish to edit an already existing branch,
first change to the correct branch using the 'branch' button in the upper left,
next to the path to the file. If you found an error in the pull request of your
own branch, you should commit to it directly instead of creating another pull
request (the two choices at the bottom).

### Making pull requests using the command-line

#### Overview:

- Clone the repository (if not done already):
`git clone https://github.com/csc-training/csc-env-eff.git`.
- Change to master branch (if not there already): `git checkout master`.
- Update your local repository: `git pull`.
- Create a new branch from the master branch: `git checkout -b my-new-branch`.
- Create content and `add` edited files in your new branch:
`git add file1.md file2.md`.
- **Hint:** Use `git add .` to add all modified files in current directory,
including subdirectories.
- Commit your changes: `git commit -m 'short description'`.
- Check status (all files committed etc.): `git status`.
- Push changes to remote repository: `git push origin my-new-branch`.
- Open a pull request to merge changes from your new branch into the master
branch.
- Ask a colleague to review and merge the changes.
108 changes: 68 additions & 40 deletions _contributing/MD_INTO_HTML.md
View file
Original file line number Diff line number Diff line change
@@ -1,72 +1,100 @@
# Convert Markdown into html, preview, and publish
# Convert Markdown into HTML, preview, and publish

## Copy the Singularity tool image to Puhti. (*e.g.* in `$HOME/bin` which is used in the examples below)
- Initialize Allas with project_2001659 (see below, works only for CSC staff)
- To get the container image use
- `a-get pandocTool/pandoc-env-eff.sif` for the EuroCC slide theme with navigation icons (contains also the old theme)
- Give execute permissions `chmod u+x pandoc-env-eff.sif`
## Copy the Singularity tool image to Puhti

> Alternatively: If you don't have Allas access use `wget https://a3s.fi/pandocTool/pandoc-env-eff.sif`
- Copy e.g. to `$HOME/bin`, which is used in the examples below.
- Initialize Allas with project_2001659 (see below, works only for CSC
staff).
- To get the container image, use `a-get pandocTool/pandoc-env-eff.sif` for the
EuroCC slide theme with navigation icons (contains also the old theme).
- Give execute permissions: `chmod u+x pandoc-env-eff.sif`.

> Alternatively: If you don't have Allas access, use
`wget https://a3s.fi/pandocTool/pandoc-env-eff.sif`

## Copy the theme and other dependencies to local directory (in Puhti)
> Note: The following recipe may not work smoothly following recent RHEL8 update. You can use the following command instead as a temporary fix to generate html files: ``` singularity exec -B $PWD pandoc-env-eff.sif /slidetools/convert.sh -s 01_my_lecture.md ``` (make sure to copy pandoc container to the directory where you are working)

1. Go the the same directory as the source md files (= your git root directory for csc-env-eff in Puhti) (If you haven't yet cloned the repository, do so: `git clone https://github.com/csc-training/csc-env-eff`). Note, this must be a subfolder in your `$HOME`.
2. Run command
Note! The following recipe may not work smoothly following recent RHEL8 update.
You can use the following command instead as a temporary fix to generate HTML
files:

```bash
apptainer exec -B $PWD pandoc-env-eff.sif /slidetools/convert.sh -s 01_my_lecture.md
```

In this case, make sure to copy the Pandoc container to the directory where you
are working.

Otherwise, the instructions are as follows:

1. Go the same directory as the source `.md` files. If you haven't yet cloned
the repository, do so: `git clone https://github.com/csc-training/csc-env-eff`.
Note, this must be a subfolder in your `$HOME`.
2. Run command:
```bash
singularity exec $HOME/bin/pandoc-env-eff.sif /bin/sh -c "cp -r /slidetools/* ."
apptainer exec $HOME/bin/pandoc-env-eff.sif /bin/sh -c "cp -r /slidetools/* ."
```
3. Now you can transform the md files to html faster and without font
embedding using simple command (include `-t csc-eurocc-2019` to use the correct theme)
3. Now you can transform the `.md` files to `.html` faster and without font
embedding using a simple command (include `-t csc-eurocc-2019` to use the
correct theme):
```bash
$HOME/bin/pandoc-env-eff.sif -t csc-eurocc-2019 01_my_lecture.md
```
4. To create a self contained html *slide* page add `-s` *i.e.* instead
4. To create a self-contained HTML *slide* page, add `-s`:
```bash
$HOME/bin/pandoc-env-eff.sif -s -t csc-eurocc-2019 01_my_lecture.md
```
5. To create the whole site add your page to the top of the Makefile (located in: csc-env-eff/_slides/Makefile) list and run `make`
5. To create the whole slide deck, add your page to the top of the Makefile
at `csc-env-eff/_slides/Makefile` and run `make`.

> Note, don't publish the theme and slidefactory accessory files, just the html (and related images etc.)!
> Note, `a-publish` will not _overwrite_ files in Allas, so you'll need to `a-put --override` or delete the file in Allas first.
> Note, don't publish the theme and slidefactory accessory files, just the
HTML. Note also that `a-publish` will not _overwrite_ files in Allas by
default, so you'll need to use `a-put --override` or delete the file in Allas
first.

## Speed up testing how the slides look like directly from Puhti

Start a local http server in Puhti and access slides with your browser
Start a local HTTP server in Puhti and access slides with your browser:

1. Go to the directory with html files (*i.e.* your csc-env git root, **not** your `$HOME`) and run command
1. Go to the directory with HTML files and run command:
```
python3 -m http.server 80XX
```
, where XX is some random number.
If the port is already in use, choose another one. Note that this example works
with default system python, so make sure that you are not using any conda or python modules.
where XX is some random number. If the port is already in use, choose
another one. Note that this example works with default system python, so
make sure that you are not using any Tykky or other Python environment.
**Note, this is an unencrypted link, don't view anything private!**
2. Launch another ssh session with local port forwarding
2. Launch another SSH session with local port forwarding:
```
ssh -L 80XX:localhost:80XX <your username>@puhti-login2.csc.fi
ssh -L 80XX:localhost:80XX <username>@puhti-login12.csc.fi
````
where XX is the port from step 1. and
login node name must match also with step 1. command.
3. Open up the pages in your local browser with a link to `http://localhost:80XX`
4. When done, please remember to shut down the server and release the port! (ctrl-c in the python3 screen does this)
where XX is the port from step 1 and login node name must also match with
the command in step 1.
3. Open up the page in your local browser using URL `http://localhost:80XX`.
4. When done, please remember to shut down the server and release the port
(ctrl-c in the python3 screen)!
## Publish html files in Allas
## Publish HTML files in Allas
1. [Initialise Allas access](https://docs.csc.fi/data/Allas/using_allas/a_commands/) with
1. [Initialize Allas access](https://docs.csc.fi/data/Allas/using_allas/a_commands/)
with:
```bash
module load allas
allas-conf project_2001659
```
2. Publish your slides
- Note, `a-publish` is recursive, so if you want only some subfolder, `cd` there first.
Leave the *CSC_training* bucket for the full repository and master branch only.
```bash
a-publish -b test-csc-env 0X_cool_chapter.html
```
- `a-publish` will echo the url, which in this case would be *https://a3s.fi/my-csc-env/0X_cool_chapter.html*
2. Publish your slides:
- Note, `a-publish` is recursive, so if you want only some subfolder, `cd`
there first. Leave the *CSC_training* bucket for the full repository and
master branch only.
```bash
a-publish -b test-csc-env 0X_cool_chapter.html
```
- `a-publish` will echo the URL, which in this case would be
`https://a3s.fi/my-csc-env/0X_cool_chapter.html`.
## Link the files in e-Lena
## Link the files in eLena
To nicely link the files in e-Lena, choose "+Add an activity or resource" -> URL -> Write the name "Slides: Topic name" and copy the Allas URL for the slides. You can write in the Description the link to github page also. Then under Appearance choose "display" = embed.
To nicely link the files in eLena, choose "+Add an activity or resource" >
URL > Write the name "Slides: Topic name" and copy the Allas URL for the
slides. You can add in the Description the link to the GitHub page also.
Then, under "Appearance", choose "display" = embed.
18 changes: 9 additions & 9 deletions _contributing/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# How to contribute

We welcome collaboration in extending and updating the content
of this guide.
We welcome collaboration in extending and updating the content of this course.

The general workflow is to create a branch (for CSC staff) or a
fork, create new content and make a pull request to the master
branch (or you're of course welcome to use your fork in your
events, as well.)
The general workflow is to create a branch (for CSC staff) or a fork, create
new content, and make a pull request to the master branch. You're of course
also welcome to use your own fork in your training events that build on this
material.

- [The general guidelines and workflow for contributing](CONTRIBUTING.md)
- [The general styleguide for slides and other content](STYLEGUIDE.md)
- [Instructions how to turn Markdown into standalone html](MD_into_html.md)
- [General guidelines and workflow for contributing](CONTRIBUTING.md)
- [General style guide for slides and other content](STYLEGUIDE.md)
- [Instructions how to turn Markdown into standalone HTML](MD_INTO_HTML.md)
- [Example tutorial page](example_tutorial.md)
Loading

0 comments on commit 9e4aa5d

Please sign in to comment.