├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── README.md ├── how_to_replicate.md ├── how_to_review.md └── updating_templates.md /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, sex characteristics, gender identity and expression, 9 | level of experience, education, socio-economic status, nationality, personal 10 | appearance, race, religion, or sexual identity and orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at opensource@github.com. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 72 | 73 | [homepage]: https://www.contributor-covenant.org 74 | 75 | For answers to common questions about this code of conduct, see 76 | https://www.contributor-covenant.org/faq 77 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing Guide 2 | 3 | Thanks for taking the time to contribute to a course on GitHub Learning Lab! :robot: :heart: :balloon: 4 | 5 | Every Learning Lab consists of two repositories: 6 | - **a course repository** containing the bot code and responses 7 | - **a template repository** containing the starter code for the hands-on project 8 | 9 | Most community contributions begin in the course repository. 10 | 11 | ### Ways to contribute 12 | 13 | We love contributions from the community. Here are just a few of the ways you can contribute: 14 | 15 | - **Report bugs:** if you find a bug while taking a Learning Lab course, you may want to do a quick check of past issues in the course repository to see if you can find any help there. Otherwise, create a new bug issue in the course repository using the provided template. 16 | - **Answer questions:** check out the open issues in the course repository to see if you can help answer learner questions. Learners also ask questions in the [GitHub community forum](https://github.community/t5/GitHub-Learning-Lab/bd-p/learn) 17 | - **Suggest changes:** this could come in the form of a new learning outcome, updates to the content, updates to the bot responses, or the logic of the course. If you'd like, you can fork the course and suggest the change that way, but most people like to talk about it first in an issue. 18 | - **Tackle an issue:** if you see an issue you would like to resolve, please feel free to fork the course and submit a PR (check out the instructions below). 19 | - **Translate a course:** if you have the ability to translate a course, we'd love to see it. Please fork the course and submit a PR. We'll need a second native speaker to confirm the translation so if you have anyone in mind, please @ mention them in your PR for a review. 20 | 21 | ### What should I know before I get started? 22 | 23 | You'll want to learn more about how Learning Lab works and courses are structured. To get up to speed, use the following resources: 24 | - take the course: [_Write a Learning Lab course_](https://lab.github.com/github/write-a-learning-lab-course) 25 | - read the [documentation on writing a course](https://lab.github.com/docs/writing-quickstart) 26 | - watch the [video on how a Learning Lab course works](https://www.youtube.com/watch?v=xaLSVcwFkiI&list=PLg7s6cbtAD147DXcVp899Fk6SegoLY9gL&index=4) 27 | - watch the [video on the `config.yml`](https://www.youtube.com/watch?v=HL8MdBsFaF4&list=PLg7s6cbtAD147DXcVp899Fk6SegoLY9gL&index=2) 28 | 29 | ### Finding open issues 30 | 31 | The [course maintenance project board](https://github.com/orgs/githubtraining/projects/1) is the place to go if you want to contribute but aren't sure _what_ to do. The project board is the unifying place to find bug reports, fixes, and course enhancements across all of the GitHub authored Learning Lab courses. It may be used in several ways: 32 | 33 | #### A new issue is opened 34 | 35 | When a new issue is opened in any of the course or template repositories for GitHub authored Learning Lab courses, they should be moved to the `Triage` column. This creates visibility for the issue. 36 | 37 | #### Triaging existing issues 38 | 39 | Maintainers of Learning Lab courses may use this board to triage existing issues. When triaging, maintainers evaluate the issue and fit it into the column that is most appropriate. The columns are sorted via priority, with highest priority issues at the top, but currently the system for determining priority is fluid. 40 | 41 | #### Finding somewhere to contribute 42 | 43 | If you want to contribute, but aren't sure how or where to start, the project board is a perfect place. You can see all of the open issues in one place. Aside from opening an issue, the main ways of contributing are to [replicate bug reports](how_to_replicate.md), [open pull requests](CONTRIBUTING.md) addressing open issues, or [reviewing open pull requests](how_to_review.md). 44 | 45 | ### How to Contribute 46 | 47 | 1. Fork the course repository AND the template repository. 48 | 1. In order to test your changes, you'll need to create your own draft version of the course on Learning Lab. You'll need to: 49 | - Install Learning Lab on both the course repository and the template repository 50 | - Go to `https://lab.github.com/{{ your-username }}/new` and provide the slug for the course repository 51 | - This will create a **draft** course. You can do all of the testing while in draft, you won't need to publish the course 52 | 1. Once you've created the draft version, you can use the Course Builder to make changes. For more information on how to make changes, check out the [documentation](https://lab.github.com/docs/writing-quickstart) 53 | 1. Commit your changes to your branch 54 | 1. Open a pull request in the parent repository with: 55 | - base branch: the default branch of the course repository, usually `main` 56 | - compare branch: the branch containing your commits in your fork 57 | - Note: If a pull request is created from a fork, then Learning Lab will not deploy a version of that course. Please ping a member of @githubtraining/programs for help. They will merge the pull request into a different branch (_not the default or original target branch_) and open a new pull request that will trigger a build of the course that can be manually tested. 58 | 1. Request a review from the Learning Lab team (this should be automatically requested) 59 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Welcome to the GitHub Training Community 2 | 3 | The `githubtraining` organization is home to all of the open source training materials and courses created by the GitHub Training team. We believe knowledge is meant to be shared and, by open sourcing these courses and project repositories, we hope you'll join us in our quest to make technology education available to everyone with the :heart: and desire to learn. 4 | 5 | ## How to use this repository 6 | 7 | This repository is intended to be a central gathering place, sorta like the town square for our Open Source Community. We'll post topics for discussion, upcoming events, and other helpful information. 8 | 9 | ## Our courses 10 | 11 | You can find all of our open source courses by [selecting the `learning-lab` topic](https://github.com/search?q=topic%3Alearning-lab+org%3Agithubtraining+fork%3Atrue) on the `githubtraining` organization page. 12 | 13 | ### Contributing to a course 14 | 15 | Check out the [contributing guide](CONTRIBUTING.md) in this repository for more information on how you can contribute to these courses. 16 | 17 | The [course maintenance project board](https://github.com/orgs/githubtraining/projects/1) features open issues and pull requests. Look here if you want to contribute, but aren't sure where to start. The [contributing guide](CONTRIBUTING.md) also features details about how to interact with this project board. 18 | 19 | ### Contributing a new bot behavior 20 | 21 | If you'd like to train the bot to do something new, you can do that in the [learning-lab-components](https://github.com/github/learning-lab-components) repository. 22 | 23 | ## We're here to help 24 | 25 | If you have questions about building (or taking) courses, you can ask them here or in the [GitHub Community Forum](https://github.community/t5/GitHub-Learning-Lab/bd-p/learn). 26 | -------------------------------------------------------------------------------- /how_to_replicate.md: -------------------------------------------------------------------------------- 1 | # Replicating bugs 2 | 3 | This document outlines the "who", the "why", and the "how" for replicating issues from the _Needs to be replicated_ column of the [Learning Lab course maintenance project board](https://github.com/orgs/githubtraining/projects/1). 4 | 5 | ## Who? 6 | 7 | If you are able to complete the Learning Lab course in question, then you are able to contribute by replicating bugs! This is a great way to contribute even if you aren't ready to submit a pull request. 8 | 9 | ## Why? 10 | 11 | We frequently get reports of bugs from the community. Frequently, when something is broken, we receive multiple reports. But, sometimes we only get one report. Before investing the time in fixing these bugs, we want to confirm a few things. 12 | 13 | - Confirm that bug is with the Learning Lab course, not other systems 14 | - Understand the scope, impact, and detail of the bug 15 | 16 | Once we have this information, we are prepared to either close the issue or move the issue to another column so that it can be fixed. 17 | 18 | ## How? 19 | 20 | 1. Read the issue 21 | 2. Sign up for the course in question, and try to duplicate the original user's situation 22 | 3. Document your experience in detail around the steps where the original user encountered problems 23 | 4. Share your notes, screenshots, and any additional detail or context in that issue and mention @githubtraining/programs 24 | 5. Someone from the @githubtraining/programs team will move this from the **Needs review** column to a more appropriate column. If you'd like to address the issue, please feel free to go ahead and open a pull request - no need to wait for it to be triaged! -------------------------------------------------------------------------------- /how_to_review.md: -------------------------------------------------------------------------------- 1 | # How to review 2 | 3 | This document outlines the steps to review a pull request in a GitHub authored Learning Lab course repository. You can find pull requests awaiting review in the "Needs review" column of the [Learning Lab maintenance project board](https://github.com/orgs/githubtraining/projects/1). 4 | 5 | Guidelines for review are based on the type of changes in the pull request: 6 | 7 | #### Minor markdown changes 8 | 9 | If a pull request is only editing minor markdown responses, (like correcting a spelling error or broken URL,) then going through the entire course to review is not necessary. These pull requests can be reviewed simply by viewing and reading the files changed. If this is the case, consider the context of the course as well as the original issue reporting a bug or requesting a change. 10 | 11 | #### Moderate to significant markdown changes 12 | 13 | If a pull request introduces moderate to significant changes to markdown, a manual review of the course is necessary. Examples of moderate to significant changes could be: 14 | 15 | - Changing the instructions of a step in a way that would cause the learner to do something different 16 | - Changing responses that include liquid syntax or other variables outside of [GitHub flavored markdown](https://github.github.com/gfm/) 17 | 18 | #### `config.yml` changes 19 | 20 | If a pull request changes the `config.yml` file, a manual review is always required. 21 | 22 | ### Manual testing 23 | 24 | Only members with specific permission are currently able to manually review the versions of courses that are deployed from pull requests. If you are a regular contributor and would like this access, please contact @githubtraining/programs. 25 | -------------------------------------------------------------------------------- /updating_templates.md: -------------------------------------------------------------------------------- 1 | # Updating template repositories 2 | 3 | Updating template repositories is particularly tricky, because there is distinct history on each branch plotted intentionally to be ready for the pull requests that a learner may interact with. For this reason, contributions to the template repository should be managed by the @githubtraining/programs team in most cases. 4 | 5 | ## Syncing the course repository 6 | 7 | In any case where a course repository is updated, a member of @githubtraining/programs will need to manually sync the template repository to the course via Learning Lab stafftools. 8 | 9 | ## Updates not affecting activities 10 | 11 | If you need to make a change to a template repository that does not affect the branches or activities, please commit directly to master. 12 | 13 | ## Updates affecting activities 14 | 15 | Changes on branches affecting activities can be complex and difficult. Template repositories cannot be synced to some versions of a course, and not others. **In these cases, it may be useful to create a fork of template repository to test separately and completely.** 16 | 17 | 1. If you do this, update the link to the template repository from the course repository's `config.yml` file. 18 | 2. Then, you can test the course from a branch with a separate template repository. Make any necessary changes to the _forked_ version of the template repository, and test. 19 | 3. Once things work as expected, force push all branches from the fork to the upstream repository. 20 | 4. **Important**: update the reference in the course repository's `config.yml` file back to the original template repository. 21 | 5. Delete the fork of the template repository. 22 | 6. Test again from the branch deployment. 23 | 7. After merging the pull request, test once more from the published and public version of the course. --------------------------------------------------------------------------------