diff --git a/org-cyf-guides/content/contributing/_index.md b/org-cyf-guides/content/contributing/_index.md index cde3f87dc..e6b266fd9 100644 --- a/org-cyf-guides/content/contributing/_index.md +++ b/org-cyf-guides/content/contributing/_index.md @@ -9,7 +9,7 @@ menu: volunteers -## 💯 Free and open +## Free and open Code Your Future is a free training programme for refugees, asylum seekers, and other people excluded from education. All our classes are free and our teachers are volunteers. Since 2016, we have supported hundreds of people into great jobs in tech. @@ -17,9 +17,9 @@ We do our work in public. Our [free and open source curriculum](https://github.c [Join our community](https://codeyourfuture.io/volunteers/). You are wanted and you are needed. -## 🤝🏽 Making Contributions +## Making Contributions -Look for issues labeled "up-for-grabs" - these are low context and suitable for new contributors. To work on an issue: +Look for issues labelled `up-for-grabs`, `help wanted` or `good first issue` - these are low context and suitable for new contributors. To work on an issue: - Comment on the issue to let others know you're working on it - Fork the repo and create a branch `feature/your-feature-name` @@ -30,22 +30,22 @@ If you've spotted a problem, please check the existing issues and join the conve When making changes, focus on clarity and beginner-friendliness. -## 🛟 Getting Help +## Getting Help If you are an outside contributor, please join discussions and open tickets on our GitHub repos. If you can @mention a core contributor, that will help us see your message. (There are hundreds of active repos, so we don't always see everything.) -If you have [joined our organisation](https://codeyourfuture.io/volunteers/), the **#cyf-syllabus-tech** channel is the best place to ask questions and get feedback. +If you have [joined our organisation](https://codeyourfuture.io/volunteers/), the **#cyf-curriculum** Slack channel is the best place to ask questions and get feedback. -You can also request a reviewers for your PR or pair program with an experienced contributor. We're happy to help new volunteers learn the codebase. There is an open code review Google Hangout once a week where you can ask questions and get feedback live. (Get the link in Slack.) +You can also request reviewers for your PR or pair program with an experienced contributor. We're happy to help new volunteers learn the codebase. Thanks for your interest! We're excited to work with you to provide life-changing education for all. -## 🧑🏿‍💻 Joining the team +## Joining the team Lots and lots of volunteers worldwide contribute to the curriculum. You don't have to join the Syllabus team to contribute, or even our our org. -But if you'd like to meet us and get more involved, [join our organisation](https://codeyourfuture.io/volunteers/) as a volunteer. Once onboarded, introduce yourself in the #cyf-syllabus-tech channel on Slack. Let us know you'd like to attend a meeting and add your agenda points to the meeting link posted in that channel. +But if you'd like to meet us and get more involved, [join our organisation](https://codeyourfuture.io/volunteers/) as a volunteer. Once onboarded, introduce yourself in the #cyf-volunteers #cyf-curriculum channel on Slack. Let us know you'd like to attend a meeting and add your agenda points to the meeting link posted in that channel. The [Global Syllabus volunteer team](contributors) meets every two weeks online to talk strategy, take issues and plan the next sprint. We'd love to meet you! diff --git a/org-cyf-guides/content/contributing/adding-updating/index.md b/org-cyf-guides/content/contributing/adding-updating/index.md new file mode 100644 index 000000000..5eaaaa45c --- /dev/null +++ b/org-cyf-guides/content/contributing/adding-updating/index.md @@ -0,0 +1,153 @@ +--- +id: adding-updating-content +title: Adding & Updating Content +description: How to locate existing files and where to put new ones +weight: 2 +--- + +## Finding the Right Directory + +CYF's curriculum is designed to be modular. Each part of the course has its own sub-directory within the `curriculum` repo, and each module within those courses has its own GitHub repo with relevant code examples and exercises. We define the structure of the curriculum by specifying where each piece of content can be found, either as a path within `curriculum` or as a GitHub url. + +> [!NOTE] +> We will use the Data Groups module of the Intro to Programming course as an example here but others follow a similar pattern. + +Within each course's directory there is a sub-directory for each module. + +```mermaid +--- +title: org-cyf-itp structure +--- +flowchart TD + itp@{ shape: docs, label: org-cyf-itp } --> onboarding@{ shape: docs, label: onboarding } + itp --> structuringData@{ shape: docs, label: structuring-data } + itp --> dataGroups@{ shape: docs, label: data-groups } + itp --> dataFlows@{ shape: docs, label: data-flows } +``` + +> [!NOTE] +> There will be additional folders with other information required to edit the page, eg. details of the next stage of the course in the `piscine` folder + +Each module is broken into **sprints**. A sprint represents one week of work. The `success` folder contains the success criteria for a module. + +```mermaid +--- +title: module structure +--- +flowchart TD + itp@{ shape: docs, label: org-cyf-itp } --> dataGroups@{ shape: docs, label: data-groups } + dataGroups --> success@{ shape: docs, label: success } + dataGroups --> sprints@{ shape: docs, label: sprints } + sprints --> sprint1@{ shape: docs, label: "1" } + sprints --> sprint2@{ shape: docs, label: "2" } + sprints --> sprint3@{ shape: docs, label: "3" } +``` + +Each sprint is made up of **prep** (material to be read before class), **backlog** exercises (exercises to attempt before class), the **day plan** (the structure of the saturday class) and **success** criteria. + +```mermaid +--- +title: sprint structure +--- +flowchart TD + itp2@{ shape: docs, label: org-cyf-itp } --> dataGroups2@{ shape: docs, label: data-groups } + dataGroups2 --> sprints2@{ shape: docs, label: sprints } + sprints2 --> sprint1@{ shape: docs, label: "1" } + sprint1 --> prep@{shape: docs, label: prep} + sprint1 --> backlog@{shape: docs, label: backlog} + sprint1 --> plan@{shape: docs, label: day-plan} + sprint1 --> moduleSuccess@{shape: docs, label: success} +``` + +## Adding Prep Work + +The `prep` directory contains an `index.md` file listing all files to be included with a module. Each entry requires two pieces of information: + +- `name` specifies the page's title in the page map +- `src` is the path to the file. This can either be a relative filepath from `curriculum/common-content/en` or a url to an external source, eg. GitHub. + +Within `common-content` prep material is split across two directories: + +- `blocks` contains content which can be reused across different courses +- `module` contains content specific to a particular module, subdivided by topic + +```mermaid +--- +title: common-content structure +--- +flowchart TD + common@{ shape: docs, label: common-content } --> en@{ shape: docs, label: en } + en --> blocks@{ shape: docs, label: blocks } + en --> module@{ shape: docs, label: module } +``` + +When adding new content: + +1. Create a new directory in the appropriate place. These can be nested within `blocks` or `modules`. +2. In your directory create `index.md` +3. Provide the appropriate front matter: + +```md ++++ +title = "Document Title" + +time = 120 + +objectives = [ + "Learning objective 1", + "Learning objective 2", + "Learning objective 3", +] + +[build] + render = "never" + list = "local" + publishResources = false ++++ +``` + +4. Write your content using markdown. Notes on styling and using render hooks can be found in the [Common documentation](https://common.codeyourfuture.io/). +5. Add the path to your content to `index.md` in the `prep` directory. + +If your content is loaded from an external GitHub url you can skip steps 1 and 2. + +Changes made to prep content should appear immediately when the site is rebuilt locally. If they do not you likely need to clear a cached version of the site. + +### Code Examples + +If code examples are required for a task they can be stored in the module's repository. Every module has its own repo named `Module-`, eg. [Module-Data-Groups](https://github.com/CodeYourFuture/Module-Data-Groups). Add code to the appropriate sprint and include a link to it in your markdown. + + +## Adding Backlog Items + +The backlogs for each sprint are generated by importing issues from GitHub. The [issues page](https://github.com/CodeYourFuture/Module-Data-Groups/issues) of each module's repo lists all exercises associated with the module with labels used to identify which sprint they belong to. + +To add a new backlog exercise, open a new issue and complete the template with the required information. Check out a [current backlog](https://itp.codeyourfuture.io/data-groups/sprints/1/backlog/) to see examples of what is required. + +To remove an item from a backlog you can close the relevant issue. + +> [!CAUTION] +> Other internal systems reference these issues - every issue **must** have labels for `sprint`, `submission` and `priority`. + +To prevent unnecessary calls to the GitHub API responses are cached. When testing locally the cache will need to be cleared in order to see changes made to GitHub issues. + + +## Updating the Day Plan + +Similar to prep work, the `day-plan` directory contains an `index.md` file laying out the structure of the day. It covers two types of content: + +- Activities repeated across multiple classes (energisers, lunch breaks, etc.). These are stored in `common-content/en/blocks`. +- Workshops for that class. + +Workshops can be defined in various places. Some are stored in `common-content/en/module` similar to prep content. + +Most workshops are stored in the [CYF-Workshops repository](https://github.com/CodeYourFuture/CYF-Workshops#:~:text=Welcome%20to%20CYF%20Workshops) and imported to `day-plan/index.md` using their url. There are some additional features available through this repository explained in its README. + +Workshops may also be created in stand-alone repositories if needed. + + +## Updating Success Criteria + +At the sprint level, the [End of Sprint Review](https://itp.codeyourfuture.io/data-groups/sprints/1/success/) page lists all learning objectives defined in prep work and backlog exercises. This is generated at build time and does not need to be manually edited. If your learning objectives are not showing up here check they are formatted correctly. + +The [End of Module Review](https://itp.codeyourfuture.io/data-groups/success/) lists the criteria for passing the module. These criteria are referenced by other teams within the organisation - please **do not edit them** without prior discussion with a member of the core team. \ No newline at end of file diff --git a/org-cyf-guides/content/contributing/contributors/index.md b/org-cyf-guides/content/contributing/contributors/index.md index 873956386..2268037e2 100644 --- a/org-cyf-guides/content/contributing/contributors/index.md +++ b/org-cyf-guides/content/contributing/contributors/index.md @@ -1,7 +1,7 @@ --- id: Contributors title: Contributors -weight: 2 +weight: 4 description: We made this together emoji: 🧑🏿‍🤝‍🧑🏿 --- diff --git a/org-cyf-guides/content/contributing/create-a-pull-request/github-branches-view.png b/org-cyf-guides/content/contributing/create-a-pull-request/github-branches-view.png deleted file mode 100644 index b8fc84069..000000000 Binary files a/org-cyf-guides/content/contributing/create-a-pull-request/github-branches-view.png and /dev/null differ diff --git a/org-cyf-guides/content/contributing/create-a-pull-request/github-fork-highlight-branches.png b/org-cyf-guides/content/contributing/create-a-pull-request/github-fork-highlight-branches.png deleted file mode 100644 index ac259b3e7..000000000 Binary files a/org-cyf-guides/content/contributing/create-a-pull-request/github-fork-highlight-branches.png and /dev/null differ diff --git a/org-cyf-guides/content/contributing/create-a-pull-request/github-fork-main-page.png b/org-cyf-guides/content/contributing/create-a-pull-request/github-fork-main-page.png deleted file mode 100644 index 9adfb71a5..000000000 Binary files a/org-cyf-guides/content/contributing/create-a-pull-request/github-fork-main-page.png and /dev/null differ diff --git a/org-cyf-guides/content/contributing/create-a-pull-request/highlight-new-pull-request.png b/org-cyf-guides/content/contributing/create-a-pull-request/highlight-new-pull-request.png deleted file mode 100644 index 598f681a1..000000000 Binary files a/org-cyf-guides/content/contributing/create-a-pull-request/highlight-new-pull-request.png and /dev/null differ diff --git a/org-cyf-guides/content/contributing/create-a-pull-request/index.md b/org-cyf-guides/content/contributing/create-a-pull-request/index.md deleted file mode 100644 index 58e0f8fdd..000000000 --- a/org-cyf-guides/content/contributing/create-a-pull-request/index.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -id: creating-a-pull-request -title: Creating a Pull Request -emoji: 📋 ---- - -## Learning objectives - -```objectives -- [ ] Locate remote branches on GitHub -- [ ] Create a pull request -- [ ] Update a pull request with a title and a relevant description -``` - -## 🔃 Comparing changes - -As developers, we often develop new features on a branch. - -When we've completed the feature, we need to **merge** our changes into another branch. - -So we'll need a way to compare changes between two different branches on GitHub. - -Let's consider the following situation. - -We have a repository like this: - -### Original repository - -```mermaid ---- -title: CodeYourFuture/GitHomeworkTest ---- -gitGraph - commit - commit - commit - commit -``` - -And there's another forked repository belonging to owner **Dedekind561**. -Dedekind561 has created a branch called `bio-page` with the new feature. - -### 🍴 Forked repository - -```mermaid ---- -title: Dedekind561/GitHomeworkTest ---- -gitGraph - commit - commit - commit - commit - branch bio-page - commit - commit - commit -``` - -> 🎯 Goal: Merge changes from the `bio-page` branch into the CodeYourFuture/GitHomeworkTest `main` branch - -## Pull Request - -To merge changes from one branch to another, we need to let other users know: - -- what the changes are -- which branches we're comparing -- additional context about the proposed change, like why we're making the change - -For this purpose, we can use a **pull request**. - -{{}} - -A **pull request** is a request to merge code from one branch into another. - -{{}} - -## Creating a new pull request - -During the course, we'll use pull requests to review your work. You'll need to push your work on a branch and then open a pull request to get feedback on your work. - -We can use the Github interface to create a new pull request. - -The steps below assume you have a forked a repository called `GitHomeworkTest` and you've pushed a branch to this remote repository. - -### Step 1 - -Go to your forked repository. The page should look like this: - -![github-fork-main-page](github-fork-main-page.png) - -Double check your url, it should be `github.com/YOUR_USERNAME/GitHomeworkTest` - -### Step 2 - -Locate the branches button on this page. - -![github-fork-highlight-branches](github-fork-highlight-branches.png) - -### Step 3 - -📝 Double check you're on a branches view like this. - -![github-branches-view](github-branches-view.png) - -### Step 4 - -Locate the **New pull request** button for the `bio-page` branch. - -![highlight-new-pull-request](highlight-new-pull-request.png) - -### Step 5 - -Double check you can see the **Open a pull request** view. - -![open-pull-request-page](open-pull-request-page.png) - -#### Questions - -a) Double check the base repository ( it should be set to `CodeYourFuture/GitHomeworkTest` ) -b) Double check the head repository ( this should be the forked repository `YOUR_GITHUB_USERNAME/GitHomeworkTest` ) -c) Double check the base branch ( this should be set to `main` ) -d) Double check the head branch ( this should be set to `bio-page` ) - -### Step 6 - -Update the pull request title to include your **region**, **name** and the **week** the coursework is for. - -![update-pr-title](update-pr-title.png) - -### Step 7 - -Update the pull request description with information about the changes on your branch. - -Below we've added a description "Create a bio page with details about myself" - -![update-pr-title](update-pr-title-description.png) - -### Step 8 - -Finally, click on **Create pull request**. - -Double check you end up with a pull request like this: - -![new-pr-landing-page](new-pr-landing-page.png) - -#### Questions - -a) Locate the **Files changed** tab and check the change you've added in your branch -b) Locate the **Commits** tab and check the commits from your `bio-page` branch - -## Using a pull request template - -Some repositories are set up with a **template** for a description, which gets automatically set in the **Open a pull request** view. - -Check the description field for any instructions to complete the pull request. - -Check out the example below: - -![update-pr-using-template](update-pr-using-template.png) - -Here there are some prompts for you to fill in information - make sure you fill it in. diff --git a/org-cyf-guides/content/contributing/create-a-pull-request/new-pr-landing-page.png b/org-cyf-guides/content/contributing/create-a-pull-request/new-pr-landing-page.png deleted file mode 100644 index 4577ae2d3..000000000 Binary files a/org-cyf-guides/content/contributing/create-a-pull-request/new-pr-landing-page.png and /dev/null differ diff --git a/org-cyf-guides/content/contributing/create-a-pull-request/open-pull-request-page.png b/org-cyf-guides/content/contributing/create-a-pull-request/open-pull-request-page.png deleted file mode 100644 index 136cf4545..000000000 Binary files a/org-cyf-guides/content/contributing/create-a-pull-request/open-pull-request-page.png and /dev/null differ diff --git a/org-cyf-guides/content/contributing/create-a-pull-request/update-pr-title-description.png b/org-cyf-guides/content/contributing/create-a-pull-request/update-pr-title-description.png deleted file mode 100644 index 8f4b63a62..000000000 Binary files a/org-cyf-guides/content/contributing/create-a-pull-request/update-pr-title-description.png and /dev/null differ diff --git a/org-cyf-guides/content/contributing/create-a-pull-request/update-pr-title.png b/org-cyf-guides/content/contributing/create-a-pull-request/update-pr-title.png deleted file mode 100644 index 94fc97422..000000000 Binary files a/org-cyf-guides/content/contributing/create-a-pull-request/update-pr-title.png and /dev/null differ diff --git a/org-cyf-guides/content/contributing/create-a-pull-request/update-pr-using-template.png b/org-cyf-guides/content/contributing/create-a-pull-request/update-pr-using-template.png deleted file mode 100644 index c6ca3c4c2..000000000 Binary files a/org-cyf-guides/content/contributing/create-a-pull-request/update-pr-using-template.png and /dev/null differ diff --git a/org-cyf-guides/content/contributing/minutes/index.md b/org-cyf-guides/content/contributing/minutes/index.md index 766c26875..e05c9537b 100644 --- a/org-cyf-guides/content/contributing/minutes/index.md +++ b/org-cyf-guides/content/contributing/minutes/index.md @@ -1,7 +1,7 @@ --- id: minutes title: Minutes of the Global Syllabus Team -weight: 2 +weight: 5 emoji: 🗒️ --- diff --git a/org-cyf-guides/content/contributing/running-locally/index.md b/org-cyf-guides/content/contributing/running-locally/index.md new file mode 100644 index 000000000..6de21d277 --- /dev/null +++ b/org-cyf-guides/content/contributing/running-locally/index.md @@ -0,0 +1,74 @@ +--- +id: running-locally +title: Building the Curriculum Locally +description: Guidance and FAQs for building part(s) of the curriculum on your machine +weight: 1 +--- + +## Required Packages + +Our curriculum is built on top of [Hugo](https://gohugo.io/) and requires some packages to be installed: + +- `go` +- `hugo` +- `npm` + +> [!WARNING] +> We require `v0.136.5-extended` of `hugo` which can be downloaded from [GitHub](https://github.com/gohugoio/hugo/releases/tag/v0.136.5) and manually added to your `$PATH`. +> +> Later versions will induce an error and building will fail. +> +> Updating this is an [open issue](https://github.com/CodeYourFuture/curriculum/issues/1505) - help welcome! + + +## GitHub Token + +When building the curriculum content is pulled from a number of different CYF repos via the GitHub API. To build locally you will need to create a fine-grained GitHub API token which can be generated from the [developer settings page](https://github.com/settings/personal-access-tokens). + +1. Click the "Generate new token" button + - Name can be anything + - Duration is not important, but if you are contributing regularly you will need to repeat this process if your token expires + - Ensure "resource owner" is your own account + - "Repository access" should be `Public Repositories (read-only)` + - You do not need account permissions +2. Clone the `curriculum` repository if you haven't already done so +3. Make a copy of `/curriculum/.env.example` +4. Rename your copy `/curriculum/.env` +5. Update the `HUGO_CURRICULUM_GITHUB_BEARER_TOKEN` property to contain the access token you just generated + + +## Directory Structure + +Each part of the CYF course is deployed to its own microsite with its own url. For example, the Intro to Programming content is found at [itp.codeyourfuture.io](https://itp.codeyourfuture.io/) and the Software Development Course is at [sdc.codeyourfuture.io](https://sdc.codeyourfuture.io/). + +Each module has its own directory within `curriculum` named `org-cyf-`, eg. `org-cyf-itp`. + +```mermaid +--- +title: Directory Structure +--- +flowchart TD + root@{ shape: docs, label: curriculum } --> guides@{ shape: docs, label: org-cyf-guides } + root --> itd@{ shape: docs, label: org-cyf-itd} + root --> itp@{ shape: docs, label: org-cyf-itp} + root --> sdc@{ shape: docs, label: org-cyf-sdc} + root --> remainder@{ shape: docs, label: ...} + itp --> content@{ shape: docs, label: content} + itp --> package@{ shape: doc, label: package.json} + itp --> readme@{ shape: doc, label: README.md} + itp --> misc@{ shape: doc, label: ...} +``` + +Within each directory is a `content` folder laying out the material for the module and a `package.json` file. To build a module: + +- Navigate to `org-cyf-` +- `npm i` +- `npm run start:dev` +- In a browser, go to `localhost:1313` + + +## Common Problems + +### Caching + +To limit unnecessary requests to the GitHub API content is cached when a module is built locally. If your changes require content to be reloaded from GitHub (eg. modifying the layout of the backlog issues) it may be necessary to manually delete the cache between builds. On a mac this is located in `/Library/Caches/hugo_cache`. Each module is cached separately. \ No newline at end of file diff --git a/org-cyf-guides/content/contributing/supporters/index.md b/org-cyf-guides/content/contributing/supporters/index.md index 47e9a03a4..e80bb2116 100644 --- a/org-cyf-guides/content/contributing/supporters/index.md +++ b/org-cyf-guides/content/contributing/supporters/index.md @@ -2,7 +2,7 @@ id: Supporters title: Partners and Supporters description: Partners and supporters donate time, money, space, and tools so we can make this work for real. -weight: 2 +weight: 3 emoji: 💷 --- diff --git a/org-cyf/content/_index.md b/org-cyf/content/_index.md index 66c0128dc..4d83468f2 100644 --- a/org-cyf/content/_index.md +++ b/org-cyf/content/_index.md @@ -1,5 +1,5 @@ +++ title="Our Courses" menus_to_map=["start here", "selection", "trainees", "fellowships"] -description="Free training for good jobs in tech | [Calendar](/calendar) | [Overview](/overview)" +description="Free training for good jobs in tech | [Calendar](/calendar) | [Overview](/overview) | [Guides](/guides)" +++