Bit Members: General Development Process
Developers should go through Stages 1-3 and reviewers should go through Stages 0-3.
This workflow streamlines the development of curriculum for a set of engaging, fun, and informative workshops which will form the basis of 3-week boot camps, each about a specific topic. Here are the boot camps we are currently working on:
- Leetcode (Data Structures and Algorithms)
- Intro to Twitter API
- Back-End Web Development (Node.js + Express.js + MongoDB: "MEN")
Stage 0 (Pre-Development): Generate issues.
Stage 1 (Pre-Review): Work on DevRel Stage 1.
Stage 2 (Post-Review): Continue perfecting DevRel Stage 1 and DevRel Stage 2.
Stage 3 (Kevin): Kevin conducts a final review.
Stage 4 (Writers): Writers proofread curriculum for grammatical errors, stylistic edits, etc.
Bullet points indicate steps, which are to be completed in order. When all the bullet points are done, the corresponding status for that stage should be marked in Airtable.
Prior to this stage, reviewers will be assigned one week of a boot camp. Depending on the task at hand, reviewers may have to create a general activity plan for their assigned week; otherwise, they are already provided an activity plan. Please consult Kevin if you are unsure about the general overview of the activities you are responsible for.
Each developer is responsible for resolving issues that add up to a weight of 10. Each issue has two labels: a category label and a difficulty label.
Issues are generated by reviewers. More details on issue creation and labeling are provided in the "For Reviewers" section.
Prior to every week's open hours, reviewers should have enough issues for the next week already made and ready to assign.
Each issue should have two labels: a category label and a difficulty label. Here are the general category labels:
- Context (explanations of underlying concepts)
- Content (code and explanations of code)
- Styling (separating cards into steps, typos, flow, only local images)
- Visuals (customizing visuals)
- Create (creating a new card)
- Ordering (card ordering, moving content from card to card)
Here are the difficulty labels for each issue:
1. Easy (Difficulty of 1)
2. Medium (Difficulty of 2)
3. Hard (Difficulty of 3)
4. Writing (Difficulty of 4)
5. Visuals (Difficulty of 5)
Easy, Medium, and Hard difficulty cards should cover DevRel Stage 1. Writing indicates any new cards or new content that need to be made. Visuals indicate custom-made visuals.
You should be naming issues with the following format:
[Activity/Lab (task_number)] (activity/lab name): (title)
Example: [Activity 2.2.1] Bookkeeper: Styling, Visuals, Rearranging Cards https://github.com/bitprj/curriculum/issues/4
For non-core modules, simply use the module name in place of the task_number.
Example: [Activity Postman.1] Testing API Endpoints: Content
A template "Activity/Lab Issue Template" is given.
The body of the issue should be separated by card. Markdown headings should be used to denote feedback given per card. For example:
- Micro to macro principle: this card should be moved to the end (main() is always at end)
- Indent code appropriately
- Indent code appropriately
- Card should be split to be more bite-sized
Please follow the template for the issues provided.
Each issue should have 2-6 bullet points. There isn't a one-size-fits-all approach to creating issues, as issues cover a wide breadth of topics. In terms of raising issues, our curriculum is based on a "Bible" that can be found here. Generally speaking, you should read the curriculum from the perspective of a student that has only learned up to the topic covered. If there is anything that should be improved based on the "Bible," it should be included in the feedback.
Here are some approaches I recommend taking if you are struggling to find an approach that works for you:
- Look at the activity/lab from the perspective of a couple of labels. Only make feedback for those labels.
- Make feedback encompassing all labels and then split them into issues depending on length.
- If there is lots of feedback for one type of label, you can just make feedback for another label!
To summarize, every issue needs to have the following:
- Properly Formatted Title
- Category Label
- Difficulty Label
- 2-6 bullet points of content, titled by card
During every Tuesday's open hours meeting, reviewers have the following responsibilities:
- Remind developers who have not met their quota to meet it during the meeting
- Assign and introduce tasks for this week (issues with weight of 10)
- If there are not enough issues, then developers need to make new issues
- Introduce activities and labs that need to be merged for the upcoming week
- Assign activities and labs to new milestones; make sure developers are clear on this
- Answer any questions or concerns developers may have
Every Tuesday, reviewers should set up individual milestones for their developers to hit for the week. Each milestone should be labeled as follows:
Week of Date of Tuesday (WK Week number of quarter) - Developer
Example: Week of 1/28 (WK 4) - Jason
Each milestone must also be marked with a due date of the next open hours meeting.
Please note that every week should have a new milestone, and each milestone needs to follow the above format.
By the end of open hours, everyone should know their milestone and where to find their tasks for the week.
To recap, each individual milestone should have:
- A proper title
- Due date of the following Tuesday's meeting
- Issues that add up to weight of 10
There are also milestones per team. Reviewers should place all the pull requests associated with their team.
After reviewers have made their milestones for the week, developers should locate their milestones to find their assigned issues. Remember, every milestone is due by the next open hours meeting.
Each developer will work in their own branch labeled by their first name.
If you are a new developer, please make a branch labeled as your first name. If you are unsure on how to use GitHub in general, please follow this guide to working on GitHub with our curriculum before proceeding.
Each developer should work on the cards that pertain to their issues in Markdown format. You can find an introduction to Markdown here: [TO DO: Markdown/Typora Guide]
When finished, developers should push their work as commits to their own branch and start a pull request from the developer's branch to their reviewer's branch. Each pull request title should have the following format:
[Activity/Lab (task_number)] (activity/lab name): (title)
Example: [Activity 2.2.1] Bookkeeper: Styling, Visuals, Rearranging Cards
If you have multiple activities or labs simply list them inside of brackets, with activity/lab name + title split by semicolon:
Example: [Activity 2.2.1, Lab 3.3] Bookkeeper: Styling, Visuals, Rearranging Cards; Minesweeper: Test Cases
For non-core modules, simply replace (task_number) with (module_name).(activity_number). If an activity number is not given, please let Kevin know.
Example: [Activity Postman.1] Testing API Endpoints: Content
In the body of a pull request, close all assigned issues followed by a bullet point summary of any changes that have been made. Make sure to mention your reviewer. Here is an example:
Closes Issues #53 #54
- Fixes content and visuals in n-Colorable Lab
- Fixes content and context associated with 1.md, 11.md, 111.md @JasonL24
A template for every pull request is provided. Please make sure to assign a stage label and an assignee (reviewer).
To make your feedback easy to understand, please click here for a guide on writing the perfect pull request from GitHub.
Afterward, the pull request should be started and assigned to your reviewer. The label "Stage 1: Pre-Review" needs to be attributed as well.
It is recommended to start one pull request for the entire week's work to make reviewers' work more manageable.
Stage 1 Summary:
- Check milestone for tasks
- Work in your own branch to resolve assigned issues
- When done, start pull request from your branch to reviewer's branch
- Make sure your pull request is properly titled
- In the body of pull request, close issues and summary
- Assign to your reviewer with "Stage 1" label
- One pull request per week
Upon being assigned a pull request from Stage 1, the reviewer should review it by checking the branch associated with that pull request on GitHub Desktop. Reviewers must check if the issues and summary in the pull request were fully addressed. If necessary, the reviewers should leave comments on the request on GitHub by going to the Files Changed tab.
After the first review, regardless of whether there are comments or not, the reviewer should change the label on the request to a Stage 2 label. Next, the reviewer should provide a summary of their review as well as the review's status (Comment/Approve/Request changes).
The developers and their reviewer will then work together to resolve those comments. Developers should commit to their pull request when working. With each commit, please be aware that the existing comments will go away. When all the comments have been resolved, the reviewer should merge the pull request.
When the reviewer has merged pull requests from the entire team, all of the issues mentioned in developers' pull requests should disappear.
The reviewer should start a pull request from his or her branch to master with all of the activities and labs titled and formatted. The titling of one lab or activity can be found here:
[Activity/Lab (task_number)] (activity/lab name): (title)
Example: [Activity 2.2.1] Bookkeeper: Styling, Visuals, Rearranging Cards
For non-core modules, simply replace (task_number) with (module_name).(activity_number). If an activity number is not given, please let Kevin know.
Example: [Activity Postman.1] Testing API Endpoints: Content
A reviewer's pull request should be similar to a developer's, the only differences being that the issues that are referenced should technically be closed and that Kevin (kavuong) should be mentioned. The label should be marked Stage 3: Final Review.
Stage 2 Summary:
- Reviewer reviews pull request in each of their developers' branches
- Reviewer leaves comments in GitHub
- Reviewer and developers work together to resolve comments
- When done, reviewer closes pull request, starts new one labeled Stage 3 to
masterwith Kevin (kavuong) assigned
In this stage, Kevin will conduct a final review and make changes when necessary. He will then work with the reviewer and developers to resolve any comments.
When all comments are resolved, Kevin will merge the request!
Once Stage 3 has completed, that indicates the development work is complete but still needs to be edited by one of our technical writers.
Kevin will raise an issue with the label Stage 4. To differentiate, Kevin will assign the issue to a technical writer. When finished, the writer should start a pull request labeled Stage 4 directly to the master branch, following the aforementioned issue template.
To be announced.
Made with 🐮 from Davis, CA