githubtraining / community-starter-kit

Course repo for Learning Lab course "Community Starter Kit"

Course: Community starter kit

This repository powers the Learning Lab course Community starter kit.

Every Learning Lab course is made up of:

• a course repository, and
• a template repository

The course repository is written in YAML and Markdown. The template repository could be written in any language that supports the learning objectives.

For more information on the goals of this course, check out the course-details.md.

Contribute

See something we could improve? Check out the contributing guide in the community contributors repository for more information on the types of contributions we ❤️ and instructions.

We ❤️ our community and take great care to ensure it is fun, safe and rewarding. Please review our Code of Conduct for community expectations and guidelines for reporting concerns.

License

All Learning Lab course repositories are licensed under CC-BY-4.0 (c) 2019 GitHub, Inc. The template repositories associated with each course may have different licenses.

When using the GitHub logos, be sure to follow the GitHub logo guidelines

community-starter-kit's Issues

Improve multiple suggested changes in README PR

The Create a README step asks the learner to update two different placeholders in the file. With these two suggested changes, if the learner accepts the first change, they get the "error" response that really isn't an error but a response to make the other change. The learner then accepts the other suggested change to move forward. Although these suggested changes are direct to the lines being changed, it may be best to use one multiline suggested change that the user can accept instead of seeing another prompt response to make the other change.

This may make the suggest change look quite big so 🤷‍♂. Just a thought.

Originally posted by @a-a-ron in #21 (comment)

Template repository needs history cleaned

The template repository for this course needs to be scrubbed in its history, so that commits are only shown by githubteacher on all branches.

Updating history

Copy and paste this into your text editor. Update the "OLD_EMAIL" field with whatever committer you're trying to erase. This will only work on the current branch, and you may need to run it multiple times to account for multiple committers.

#!/bin/sh

git filter-branch -f --env-filter '

OLD_EMAIL="[email protected]"
CORRECT_NAME="GitHub Teacher"
CORRECT_EMAIL="[email protected]"

if [ "$GIT_COMMITTER_EMAIL" = "$OLD_EMAIL" ]
then
    export GIT_COMMITTER_NAME="$CORRECT_NAME"
    export GIT_COMMITTER_EMAIL="$CORRECT_EMAIL"
fi
if [ "$GIT_AUTHOR_EMAIL" = "$OLD_EMAIL" ]
then
    export GIT_AUTHOR_NAME="$CORRECT_NAME"
    export GIT_AUTHOR_EMAIL="$CORRECT_EMAIL"
fi
' --tag-name-filter cat -- --branches --tags

Need YAML

This is ready for the YAML treatment @JasonEtco

Thinking about the community starter kit

I went through this course late last night and it is a bit task based at the moment, so I have been contemplating the story we are trying to tell in this course. This issue is a bit stream-of-consciousness so I apologize in advance for flooding anyone who sees it with so many words 👼

Learning Goals

There are a few learning goals we should address for maintainers as a whole - these are extreme generalizations of the journey a successful open source maintainer may take:

• How to create a project that others will use
  • because people typically contribute to projects they use
  • are the benefits and features clear?
  • can users figure out how to use the project in less than 1 hour?
  • is it well documented? (both documentation and code comments)
  • is there a template or reference implementation?
• Recognizing the many ways people will contribute (and making it easier)
  • the on-ramp for a contributor typically involves bugs --> feature recommendations --> PRs
  • this may vary for more experienced contributors
  • are there systems in place to organize this work?
  • is it easy to understand your expectations for contributions?
  • is it easy to understand the type of contributions that are most helpful?
• Making your project easy to find
  • how do search and recommendations happen on GitHub
  • what tools help GitHub categorize your project for search and recommendations
  • what can you do to "get the word out" about your project via other open source efforts?

Topics currently covered in this course

• Add topics
• Add labels
• Add repo description
• Collectively:
  • Code of conduct
  • Contributing guide
  • License
  • README
  • issue/PR templates
  • pointer projects 🤔

Telling a story that supports the journey

• The code is only the beginning. Mona has created a simple probot app and she wants to make it open source.
• (1) First she updates the repo description and creates a README so that others know what it does
• (2) She creates some simple docs with info on how to install and use her probot app
• (3) She adds some issue templates so she can get the information she needs when people report bugs
• (4) She creates some labels to organize issues as bugs, features, documentation, etc
  • She adds more labels to help her tag issues for first-time-contributors, etc
• (5) She creates a contributor guide that explains how to set up the app locally for testing
• (6) She adds a License so others can contribute with confidence
• (7) She adds a Code of Conduct to let the community know she's serious about how others are treated in this project
• (8) She adds some topics to make her project easier to find
• (9) She thinks about ways to make her project more visible to those who will find it useful (e.g. pointer projects)

Focusing on the right learning outcomes

I want the learner to focus on the value of the documentation, labels, etc and not what they should contain. For example, I don't want them to have to go out and figure out how to install a probot app -- instead, I will create this content on branches.

Other than LL, where can learners find this course?

What if this course was linked in the GitHub UI, would it still be useful? If it is linked on the community score page is this story based format still the right approach?

If the learner could choose to install this course on an existing repo, what would we do differently? In this case, the story based approach might not work as well. The steps would be the same, but it would be about the learner's repo .... I think the ability to make this meaningful is still a long way off.

Should instructions be different for private vs. public?

I don't think so - if they are taking a course on community then let's assume they are doing it because they want to make it open source. The community score page isn't available if the repo is private so they will need to make the docs the hard way, but that can also be something we discuss.

Avoiding a word flood

I really wish we could embed videos 😦 maybe we can find interesting ways to present some content as tips and tricks when transitioning between steps??

Wrong URL in `responses/08n-next.md` file

Bug Report

Current behavior
The URL mentioned in the following message points to a pull request https://github.com/<username>/community-starter-kit/pull/8

All of the necessary files are complete! Now we just need to help Mona get eyes eyes on her project. I have a few ideas that might help and I've dropped them in this issue.

Reproduction
Steps to reproduce the behavior in the course:

1. Enroll into the community starter kit course.
2. Complete all the steps up to step 14 "Merge the Code of Conduct"
3. When this 14th step is completed, the following message by github learning lab bot will be displayed.

All of the necessary files are complete! Now we just need to help Mona get eyes eyes on her project. I have a few ideas that might help and I've dropped them in this issue.

4. When clicked on this issue, instead of redirecting to the required issue, it redirects the user to a pull request(the same one on which the above message is displayed).

Expected behavior
The URL mentioned in the above message should point to an issue https://github.com/<username>/community-starter-kit/issues/9

Possible solution
I have checked the response of the github-learning-lab bot in this file and it appears that the link stored in the issueURL variable might be incorrect. Although the link stored in the store.visibilityIssueUrl variable is correct(which is used in another response of bot just below the original one). So, replacing issueURL variable by store.visibilityIssueUrl should work.

Additional context
Add any other context about the problem here. If applicable, add screenshots to help explain.

Course suggestions from community forum

From the community forum, a user recommended the following improvements to instructions:

• Add text into the issue #1 that states something like:
  • "Be careful not to edit the text of the description of the README.md. It will cause a merge conflict later."
• Add text into the pull request that states:
  • "Be careful when committing your changes. You have to do this twice, and the green commit button is located in two different spots.
  • The first time, commit in the code review. This commits the suggestions from the pull request to the branch.
  • The second time, commit the add-doc branch to the master branch for more info about branching see this video and (give link back to the one you created for you GitHub tutorial) and or take our other course(give link to GitHub-lab-tutorial)."
  • If you don't see the green commit button after doing the 1st scroll down more on this pull request to see the button.
  • Please also note: There also a difference between a merge where your work with someone else, and a comment where you just approve of the changes of someone else work without much modification."

Need those editing eyes!

Hey @a-a-ron I would love some 👀 on this course before I ask for the training team to review it.

BUG - course stuck

A user opened a community forum post:
https://github.community/t5/GitHub-Learning-Lab/Community-Starter-Kit-Edit-the-README-md/m-p/13194/highlight/false#M298

I looked into her problems, and she'd done everything right, but the bot stopped responding. I tried triggering things automatically in stafftools, but it didn't do anything.

Her repository can be found here: TashaPenwellHC/community-starter-kit#2

cc @githubtraining/learning-engineering

possible typo in course-details.md file

From the Prerequisites section of course-details.md file

In this course you will work with issues and pull requests, as well as edit files. If these things are familiar to you, we recommend you take the [Introduction to GitHub]({{ host }}/githubtraining/introduction-to-github) course, first!

In the second sentence, do you mean "If these things are not familiar to you, we recommend you take the [Introduction to GitHub]({{ host }}/githubtraining/introduction-to-github) course, first!" instead ?

BUG - Files must be snake case

A user has reported some bugs in this course that lead to files not being recognized properly on the community forum.

I am learning issue template through Community Starter Kit course. However, by default, files follow kebab case which seems not be recognized:
user-question.md
bug-report.md
When going to Settings > Issue template, I realised that file name should be snake case. Indeed, after renaming to user_question.md and bug_report.md, these templates appear.
Also, the header

---
name: template name
about: template description
---

seems to be required.

@githubtraining/trainers @githubtraining/learning-engineering I don't know if I will have bandwidth to fix this soon, but if anyone does, it should be a relatively quick fix.

Improve experience for label step

The step to add a label is 8 steps long. It may be good to include a gif to highlight the steps to make it easier to grasp the steps all at once. A learner may be scrolling back and forth to read the instructions

Originally posted by @a-a-ron in #21 (comment)