Skip to content

Commit

Permalink
docs: update create workshop
Browse files Browse the repository at this point in the history
  • Loading branch information
@sinedied
sinedied committed Jun 4, 2024
1 parent 9541d62 commit 8f21559
Show file tree
Hide file tree
Showing 7 changed files with 67 additions and 83 deletions.
Binary file removed workshops/create-workshop/assets/copy-url.png
View file
Binary file not shown.
Binary file added workshops/create-workshop/assets/create-codespace.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed workshops/create-workshop/assets/create-pr.png
View file
Binary file not shown.
Binary file added workshops/create-workshop/assets/create-repo-from-template.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed workshops/create-workshop/assets/fork.png
View file
Binary file not shown.
Binary file removed workshops/create-workshop/assets/open-pr.png
View file
Binary file not shown.
150 changes: 67 additions & 83 deletions workshops/create-workshop/workshop.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,12 @@ In this short tutorial, you'll learn how to create 🌟 a new workshop 🌟 and
## Prerequisites

| | |
|----------------|-----------------|
| Git | [Download Git](https://git-scm.com) |
| Node.js v16+ | [Download Node.js](https://nodejs.org) |
| GitHub account | [Create free GitHub account](https://github.com/join) |
| A code editor | [Download VS Code](https://code.visualstudio.com/Download) |
| A browser | [Download Microsoft Edge](https://www.microsoft.com/edge) |
|------------------------------------------------|-------------------------------------|
| Git | [Download Git](https://git-scm.com) |
| Node.js v20+ *(only needed if using MOAW CLI)* | [Download Node.js](https://nodejs.org) |
| GitHub account | [Create free GitHub account](https://github.com/join) |
| A code editor | [Download VS Code](https://code.visualstudio.com/Download) |
| A browser | [Download Microsoft Edge](https://www.microsoft.com/edge) |

You can test your setup by opening a terminal and typing:

Expand All @@ -40,62 +40,25 @@ You should see the installed tools version in the terminal.

---

# Initial setup

1. Open https://github.com/microsoft/moaw in your browser, and select the **Fork** button in the top-right corner of the page.
![Fork button](assets/fork.png)

2. Select the owner of the fork, and click **Fork**.

3. Select the **Code** button, and copy the URL of the forked repository.
![Copy URL](assets/copy-url.png)

4. Open a terminal and clone the forked repository:

```sh
git clone <forked-repo-url>
```

5. Navigate to the cloned repository and install the dependencies:

```sh
cd moaw
npm install
```

You're now ready to create a new workshop!

<div class="tip" data-title="tip">

> You only need to do the initial setup once. You can skip it next time you want to create a new workshop.
</div>

---

# Create a new workshop

Open a terminal, and copy the workshop folder `template/workshop` to the `workshops/` folder, and give it a name (you can also do it from your file explorer if you don't have a bash terminal):
1. Open https://github.com/sinedied/moaw-workshop-basic/ in your browser, select **Use this template** button in the top-right corner of the page, then select **Create a new repository**.
![Create new repository button](assets/create-repo-from-template.png)

```sh
cp -r template/workshop workshops/<your-workshop-name>/
```
2. When the repository is created, you can either clone it locally, or select the **Code** button, then the **Codespaces** tab, and **Create codespace on main** to open the repository in a browser-based development environment.
![Create codespace button](assets/create-codespace.png)

<div class="tip" data-title="tip">
You're now ready to work on your workshop!

> Pick a short but meaninful name for the folder, using the **kebab-case** convention (e.g. `create-workshop`).
</div>

<div class="warning" data-title="warning">
<div class="tip" data-title="tip">

> Make sure sure to add a trailing `/` in the URL, otherwise you might end up with a 404 error.
> There's also a more [advanced starter template](https://github.com/sinedied/moaw-workshop-advanced) that you can use instead of the basic one, that includes scripts to create one or more packages and setup the initial project structure.
</div>

## Edit the workshop metadata

Open the file `workshops/<your-workshop-name>/workshop.md` in your code editor, and edit the front matter at the top of the file:
Open the file `docs/workshop.md` in your code editor, and edit the front matter at the top of the file:

```yaml
---
Expand Down Expand Up @@ -380,20 +343,7 @@ Once your workshop is ready, you can preview it in your browser to make sure eve

## Test your workshop locally

To preview your workshop locally, you can to start the local development server:

```sh
npm start
```

This will start a local development server on port 4200.

You can then open [`http://localhost:4200/workshop/<your-workshop-name>/`](http://localhost:4200/workshop/<your-workshop-name>/) in your browser to preview your workshop.


### Use MOAW CLI

You can also use the MOAW cli to preview your workshop locally, even if you are **writing your workshop in another repository**. First, you need to install the MOAW CLI with npm.
To preview your workshop locally, you can use the MOAW CLI. First, you need to install it with NPM:

```sh
npm install -g @moaw/cli
Expand All @@ -402,47 +352,52 @@ npm install -g @moaw/cli
You can then launch the CLI with the `s` command (as in _serve_) and passing the path to your workshop file.

```sh
moaw s docs/workshop.md
moaw serve docs/workshop.md
```

## Host workshop from your repository

## Host workshop from your fork

You can also host your workshop directly from your GitHub fork, so that you can share it with your colleagues or friends.
You can also host your workshop directly from your GitHub repository, so that you can share it with other folks.

First, commit and push your changes to your fork:
First, commit and push your changes to your repository:

```sh
git add .
git commit -m "Add <my-workshop>"
git commit -m "Update <my-workshop>"
git push
```

You should now be able to access your workshop using this url:

`https://aka.ms/ws?src=gh:<your-github-username>/moaw/main/workshops/<your-workshop-name>/`.
`https://aka.ms/ws?src=gh:<your-github-username>/moaw/main/docs/`.

This is also a convenient way to quickly host your workshop without having to wait for it to be published on the main website.
You can also use the MOAW CLI to generate the URL for you:

```sh
moaw link docs/workshop.md
```

<div class="info" data-title="Note">

> If you make changes to your workshop, it may take a few minutes after the changes have been pushed to your fork before they are visible on the hosted version, as GitHub caches the content.
> If you make changes to your workshop, it may take some time after the changes have been pushed to your repository before they are visible on the hosted version, as GitHub caches the content.
</div>

---

# Publish your workshop

When you are ready to publish your workshop, you can submit a pull request to the main repository.
When you are ready to publish your workshop, you can submit a pull request to the main MOAW repository to get your workshop listed on the MOAW website.

## Update workshop metadata

First, update your workshop metadata to set the `published` field to `true`:
First, you have to update your workshop metadata to set the `published` field to `true`:

```yaml
published: true
```

Then, make sure you have committed and pushed all your changes to your fork:
Then, make sure you have committed and pushed all your changes to your repository:

```sh
git add .
Expand All @@ -456,16 +411,45 @@ git push
</div>

## Creating a pull request
## Creating a pull request on the MOAW repository

Next, we'll create an entry for your workshop to get it listed on the MOAW website.

1. Edit the `external.yml` file by opening [this link](https://github.com/microsoft/moaw/edit/main/packages/database/external.yml) in your browser.

2. Select the **Fork this repository** button to create a fork of the MOAW repository, which will allow you to make changes to the file.

3. Add an entry for your workshop at the end of the file, following the existing format (most of these fields are identical to your workshop metadata):
```yaml
- title: Full workshop title # Required. Title of the workshop
description: This is a workshop for... # Required. Short description of the workshop
url: https://workshop.url # Required. URL of the workshop
language: en # Required. Language of the workshop, using 2-letter ISO code
last_updated: 2019-10-21 # Required. Date of the last update of the workshop
type: workshop # Required. Only 'workshop' is supported for now
level: beginner # Required. Can be 'beginner', 'intermediate' or 'advanced'
github_url: https://github.url # Optional. URL of the workshop's GitHub repository
authors: # Required. You can add as many authors as needed
- Name
contacts: # Required. Must match the number of authors
- Author's email, Twitter...
banner_url: https://banner.url # Optional. URL of a banner image for the workshop (1280x640px)
video_url: https://youtube.com/link # Optional. Link to a video of the workshop
duration_minutes: 120 # Required. Estimated duration in minutes
audience: students, pro devs # Optional. Audience of the workshop (students, pro devs, etc.)
tags: javascript, api, node.js # Required. Tags for filtering and searching
```

<div class="important" data-title="important">

Finally, submit a pull request to the main repository:
> Make sure to keep the indentation consistent with the rest of the file, otherwise the YAML file will be invalid.
1. Open your fork on GitHub, select the **Contribute** button then click on the **Open pull request** button:
</div>

![Open a pull request on GitHub](assets/open-pr.png)
4. Once you've completed the entry for your workshop, scroll up and select the **Commit changes...** button to save your changes to the file.

2. Enter a title and description for your pull request, and select the **Create pull request** button:
5. Enter a commit message, and select the **Propose changes** button to move to the next step.

![Create a pull request on GitHub](assets/create-pr.png)
6. Select the **Create pull request** button to create a pull request with your changes.

That's it! Your workshop will be published on the main website once the pull request has been reviewed and merged. 🚀

0 comments on commit 8f21559

Please sign in to comment.