Dev meeting recap and next steps!

[Melissa Kline]

Thanks to all who took the time to join the call - it was great to 'meet' many of you for the first time and hear about all the progress that's happened already! You can find our (pretty brief) meeting minutes here. 

Post meeting, there are four specific kinds of contributions and help that we're looking for! Some of these tasks will involve GitHub, in particular making issues in repositories. If you haven't done this before, see the bottom of this email. 

(1) Help write the validator

    (1.5) Fill out your availability for the next developer meeting!

(2) Align the validator and technical specification

(3) Prune and resolve comments in the technical specification

(4) (Everyone!) Test the browser validator and ask questions

***

(1) Help write the validator

Felix and Alexander have done a *ton* of coding, creating a validator which has a shared codebase for both the browser (no software, no coding needed) and R package versions of the Psych-DS specification. Don't listen to a word Felix says about just a couple of hours hacking on a rainy afternoon. 

That said, they are keen to keep going and have several places where they can use extra hands. If you would like to do this (especially if you have experience in R, JSON Schemas or JavaScript), you should fork the repository to your own github account. Then, if you are making proposed changes, you will submit a pull request back to the main repository. Here is a brief overview of the workflow for this; we also stand ready to help people navigate!

***

(1.5) Fill out your availability for the next developer meeting!

Below are some initial tasks that will go a fair ways toward identifying some next steps, but it will also help to get a nitty-gritty introduction to the codebase from Felix H. The next dev meeting will focus on this. Our sweet spot for meeting across time zones is fairly narrow, so I've made a link with just a few hours per day, and we'll try to find a day that many of us can attend.

If you'd like to attend the next meeting, please fill in your availability here. If all has gone well, you should see times that make sense for your time zone! (Early morning for west coast North America, mid day for east coast, late afternoon/evening in Europe).

***

(2) Align the validator and technical specification

Felix gave a nice summary in an earlier message of which parts of the specification are implemented in the code, but so far only he & Alex know exactly where each part is! We'll want to make sure we can check off against a list of features, and to do this, it will help to make the 'guts' of the technical specification a bit more granular, and to number the specific rules so we can refer to them. 

We came up with a pattern to start this process: 

- First, find a part of the spec that you feel good about your understanding of. If it contains more than one requirement, try and break it down into a list of requirements. Number the requirements if they are not already numbered. (Use the section numbers and 'dot' notation to number things. E.g. 3.1.1, 3.1.2, etc.)

- Next, go to the validator repository, and check the issues page. If there is not already an issue about this number, make a new issue, which looks like the following: 

Name: "Verify that validator implements 3.1.2 (Short description of the feature, e.g. UTF-8 Encoding" )" 

Contents: Describe which feature/requirement this is. If you can tell whether or not the validator seems to be respecting it, you can comment on this too. 

That's it! We'll use this as a starting place to discover what's left to do, and whether the spec and validator are agreeing with each other. 

***

(3) Prune and resolve comments in the technical specification

Going along with #2, the tech spec document is currently teeming with post-SIPS chatter and questions. Anyone can help us move forward by grabbing a comment or block of suggested text and 'resolving' the comment by determining if there's more discussion to be had, and moving it forward in one of these ways:

(a) If it's more of a developer/technical issue (should JSON be formatted like this or like that?), you can turn the comment into an issue on the validator repository. Make sure you let the person whose comment it is know (link to the issue) where their comment is going!

(b) If it's more of a general or user-oriented question, something that the whole group might need to weigh in on, you can bring it to the group by starting a new conversation on the google group. (Again, let the commenter know where their comment is going!) 

I'll model this pattern later today :)

(c) If it doesn't seem to belong in either of those places, shoot me an email (or tag me in the comment) and we'll figure it out!

***

(4) (Everyone!) Test the browser validator and ask questions

Anyone who is interested can check out the in-browser validator right now(!!) You can test the browser in two ways. First, you can just point it at a random file on your computer. Second, you can download a sample dataset from the example-datasets repository. See what errors you get, or experiment with moving files around in the example dataset folder to see what happens. 

Right now, the single most important thing we can learn is what experience people have when they land on this website! Do you see what to do when you arrive? If you get an error message, do you know what it means? Do you know when in your workflow you'd use this validator? 

This is likely to generate questions, or even worse, a general feeling of 'stuckness'. If this happens, please tell us how & where! You can email me or Felix H., or make a github issue explaining the problem. (Instructions below). 

*****

Thank you all again for staying involved in this project, it's been (and continues to be) a real treat!

- Melissa

*****

Bonus content: How to make a GitHub Issue

Github 'issues' are just conversations that are organized around a very specific problem or question that needs to be solved in a project. They form a group 'to-do' list for everyone working on the project. Here is how to use them:

(1) Make an account on GitHub if you don't have one already

(2) Go to the repository webpage for the tool you're working on or trying out. For the browser validator, the address is https://github.com/psych-ds/validator-prototype

(3) Near the top of the page, click on the Issues tab:

(4) You should see the issues page below. There is a green button on the right side of the screen to make a new issue, but you can/should also start by looking at the current issues. Issue #2 (Thanks Peder!) shows a good example of an issue dealing with an error message

(5) That will take you to a form to fill out. Use the header to give a *short* description of the issue, and then add a longer description below. Including screen shots or specific examples is a plus. 

****

That's it, that's the whole email. Here's a capybara:

[Melissa Kline]

Thanks to those who filled out their availability - the next developer meeting will be at 11AM EDT (8AM WDT, 5PM CET) on Friday, October 4. 

Felix H. will give us a nitty-gritty tour of the validator code so far, and we'll talk about next steps! You can find the agenda, Zoom link, and details for the call here. If you have other topics of discussion, please add them to the agenda, and if you have more specific questions or bug reports about the validator, you can also check out the issue list.  

If you're not sure if this meeting is for you, (1) It is! We'd love to have you there if you're at all interested in understanding how the validator works or learning how to contribute and (2) please feel free to contact me with any questions. 

- Melissa

[Melissa Kline]

A reminder that the developer call is at 11AM EDT (8AM WDT, 5PM CET) today - links to check your local time and connect to the call are below.