Refactoring the gh-classroom / nbgrader approach

[lwasser]

@jlpalomino and I spent some time working through the workflow for github classroom.

Essentially, we'd like to take the scripts here and turn them into components for abc classroom that can be run at the CLI.

The high level workflow is outlined below. From this we will have several issues and questions to address before we can do further work! The one SIGNIFICANT chance from those scripts will be using a config.yml file like we use here in abc-classroom. More on that will be specified below.

Proposed Config File

Below we begin to proposed the structure of a config file. This config file would map closely to abc-classroom's existing functionality however, it would have some additional components as well.

config.yml assumptions:

• You are working in the nbgrader class repo (i think that will be important but i presume you could use the page to it as well??
• here is an example of a abc-classroom config file

- org_name:
- course_name:
- assignments:
  # List all assignments as they are created here. 
  - assignment-name-one
      - deadline:
      - ???

# Additional files that will always be added to the student assignment repository
# In this example the file called `student_README.md` will be copied to the
# student's repository as `README.md`
- assignment_repo_files:
  - README.md: student_README.md
  - environment.yml: environment.yml
  - .gitignore: .gitignore

The above is a start to the config file use. Note that the original config also included student GH usernames. there will need to be an independent discussion surrounding how the student roster is populated.

2. Create a Classroom

2a. Create a nbgrader class repo / directory

• This is the directory where the nbgrader DB and such is housed. This step is soley nbgrader functionality but we might consider wrappers around this step and step 2b below

2b. Create a GitHub Classroom Class.

Questions Surrounding Creating a Class

• Can we use the API to create a new classroom or does this step need to be manual? I suspect the answer to this is "no" but i asked anyway!! it's ok to have a manual step in our process. it's a small step and only performed once.
• Meta classroom question - could steps 1a and 1b be merged via a wrapper with a config file IF you can use the API for GH classroom?? see this question here

UPDATE: I DON'T BELIEVE THAT WE CAN AUTOMATE CREATING A GITHUB CLASS. This is ok as it's a one time step.

3. Create Assignment (Nbgrader)

Here the instructor needs to create an assignment that will be distributed to students. It involves several steps.

• Instructor builds notebook with tests
• Instructor validates notebook with nbgrader
• instructor assigns the assignment which creates a copy of it in the release folder.

These tasks can all be implemented using nbgrader. It would be good for us to document this in our docs just to have it here. We have some of this documented in our hackmd document. Earth Lab can develop these docs.

4. Create / Distribute Assignment (Github)

The steps here are contingent upon another question - I think a wrapper is created that both creates the assignment via nbgrader and produces the github repo all in one step. But you could also do these things independently to make this more versatile. we have all of the information needed at this step to implement both.

• Here is the github module with the GH functions

• AND here it the function that we want to call - YAY!! essentially this should make the template and push it to our org!

• [ ] We will need to update the docs about these steps but we started this here: https://hackmd.io/0ZbGctpuSdqYK2OdPI51dw

This should be possible. as a baby step we have a abc-create-assignment

Last Steps

I suggest that for now we refactor our scripts to implement the steps below using the config file which will remove many of the arguments that are used over and over again. i think each function will just need to call the assignment name and the rest should work... More soon on the roster issue which is a whole different can of worms.

The last 4 steps are:

5. collect assignments
6. Grade assignments
7. Generate Feedback 8 Push feedback to students

[lwasser]

@kcranston here is the start of our brainstorming. i have a pretty clear idea of what we'd like to implement based upon this. I think we should start with implementing

1. moving the scripts over to abc-classroom
2. implementing the config file so that variables are available to all modules as needed in abc-classroom

But i'll create a new issue for this and only after we talk about it a bit more. i just wanted you to see where we are going with this all first.

[kcranston]

This looks great! I'll take a deeper dive early next week when I get back home and be prepared with some time / effort estimates for implementation during our meeting next week.

[lwasser]

Starting this google doc to outline what the functionality would look like here and to highlight the differences.

https://docs.google.com/document/d/144TMER_PR8c5cCk7ztVShNwy7fFLAXptcBny9D0L9Kk/edit

[lwasser]

@kcranston i think i have a really good idea of where we should start here !! looking forward to chatting more next week. I'll spend just a bit more time on budget and such monday but the scope is definitely coming together here after spending some time on both the scripts and abc-classroom today!!!