Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add warning about trailing forward slash #217

Merged
merged 2 commits into from
Dec 3, 2024
Merged
Changes from all commits
Commits
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
7 changes: 7 additions & 0 deletions learners/migrating-from-styles.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
**_We strongly recommend that you create a backup of your lesson repository before you follow this workflow._**
:::

:::::::: prereqs

Check warning on line 17 in learners/migrating-from-styles.md

View workflow job for this annotation

GitHub Actions / Build markdown source files if valid

[unknown div] prereqs

## Prerequisites

Expand All @@ -32,11 +32,11 @@

## Transition Workflow

1. [Set up the transition tools](#workflow-setup)

Check warning on line 35 in learners/migrating-from-styles.md

View workflow job for this annotation

GitHub Actions / Build markdown source files if valid

[missing anchor]: [Set up the transition tools](#workflow-setup)
2. [Create an Rscript for your lesson](#Rscript)

Check warning on line 36 in learners/migrating-from-styles.md

View workflow job for this annotation

GitHub Actions / Build markdown source files if valid

[missing anchor]: [Create an Rscript for your lesson](#Rscript)
3. [Run the transition tool](#transition)

Check warning on line 37 in learners/migrating-from-styles.md

View workflow job for this annotation

GitHub Actions / Build markdown source files if valid

[missing anchor]: [Run the transition tool](#transition)
4. [Set up your GitHub repository to receive the transitioned lesson](#github)

Check warning on line 38 in learners/migrating-from-styles.md

View workflow job for this annotation

GitHub Actions / Build markdown source files if valid

[missing anchor]: [Set up your GitHub repository to receive the transitioned lesson](#github)
5. [Post-transition steps](#post-transition)

Check warning on line 39 in learners/migrating-from-styles.md

View workflow job for this annotation

GitHub Actions / Build markdown source files if valid

[missing anchor]: [Post-transition steps](#post-transition)

::: callout
Note: these steps assume your lesson exists in The Carpentries Incubator i.e. under the `carpentries-incubator` organisation on GitHub. If it does not, you will need to replace all of the folder names etc below accordingly.
Expand Down Expand Up @@ -84,11 +84,18 @@

It is sufficient to create an empty file, named appropriately. This is available in the add-lesson.sh file, which will also provide hints about how the data can be transformed.

::::::::::::::::::::::::::::::::::::::: caution

It is essential that you do not include a trailing `/` after YOUR-LESSON-NAME below.)

:::::::::::::::::::::::::::::::::::::::::::::::


```bash
bash add-lesson.sh carpentries-incubator/YOUR-LESSON-NAME
```

But you may wish to populate this script with some function calls to clean up various common artifacts produced by the transition, or to preserve any [custom workflows](#custom-workflows) you have added to your lesson repository. Look at the `.R` scripts in the [`carpentries-incubator/`](https://github.com/carpentries/lesson-transition/tree/main/carpentries-incubator), [`datacarpentry`](https://github.com/carpentries/lesson-transition/tree/main/datacarpentry), [`librarycarpentry`](https://github.com/carpentries/lesson-transition/tree/main/librarycarpentry), and [`swcarpentry`](https://github.com/carpentries/lesson-transition/tree/main/swcarpentry) directories of the `lesson-transition` repository for inspiration.

Check warning on line 98 in learners/migrating-from-styles.md

View workflow job for this annotation

GitHub Actions / Build markdown source files if valid

[missing anchor]: [custom workflows](#custom-workflows)

### 3. Run the transition tool{#transition}

Expand Down Expand Up @@ -150,7 +157,7 @@
To check how things are looking, [install the Workbench tools for your system](index.html#installation), then open R in this directory and run `sandpaper::serve()`.

#### Optional: update your lesson's R script to produce a smoother transition
While previewing this transitioned lesson site, you might see some problems in the content of your lesson site that appeared during the migration. Liquid comments (delineated by `{% comment %}` and `{% endcomment %}` tags) are one commonly-encountered artifact. Another is broken links to the lesson setup instructions, which are found at `index.html#setup` in a Workbench site. These can be fixed by editing the lesson after transition, but for a cleaner commit history on your lesson you might wish to delete the transitioned lesson directory (inside the `release` folder), modify the R script for your lesson to handle those issues, and re-run the transition tool. (See [_Create an Rscript for your lesson_](#Rscript) above.)

Check warning on line 160 in learners/migrating-from-styles.md

View workflow job for this annotation

GitHub Actions / Build markdown source files if valid

[missing anchor]: [Create an Rscript for your lesson](#Rscript)

#### If something goes wrong
To go back to the start and try again, delete the directory for your lesson within the `release/` directory, i.e. `rm -rf release/carpentries-incubator/YOUR-LESSON-NAME`.
Expand Down
Loading