Design the data format of a Project

phil-ociraptor commented 4 years ago

Problem

We need to nail down the data format of a project that will be shared between the frontend and where ever our data is stored. Doing so will decouple engineers working on the UI/UX and those working on the data representation, and allow us to parallelize our efforts.

Objective

Some sample json is fine, but that sample will become our interface, so it's extremely important to do this with care.

For example, we could say it might look like:

{
  "projectName": "SoS Website",
  "description": "This is the project that powers this website",
  "gitHubURL": "https://github.com/phil-ociraptor/sos-landing"
  ...
}

For the rest of the fields, refer to our project tracker for what we're currently using: https://tinyurl.com/sos-projecttracker

But feel free to suggest changes for what fields we should be tracking.

Collaborators

This will be owned by the data team: @esu2020 @pandevim @justonsky

Although more input from the rest of the team will only help.

Deliverable

Just a sample JSON for one project.

kdmarble commented 4 years ago

We could add in a contributors object that uses their name as a key, and a link to their github/portfolio/linkedin/etc as a value:

{
  "projectName": "SoS Website",
  "description": "This is the project that powers this website",
  "gitHubURL": "https://github.com/phil-ociraptor/sos-landing"
  "contributors": {
        "first user": "linkedin.com",
        ...
  }
  ...
}

Leeoku commented 4 years ago

I think we should add something similar to our groupings. Since we technically have different "streams" people can be interested in different things


{
  "projectName": "SoS Website",
  "category": "Web/Python/Game/AI/ML/Etc
  "description": "This is the project that powers this website",
  "gitHubURL": "https://github.com/phil-ociraptor/sos-landing"
  "contributors": {
        "first user": "linkedin.com"
        ...
  }
  ...
}

alecbar commented 4 years ago

What fields could we include to show prospective collaborators if there are still open spots or not to join the project team? And how to go about joining?

Also fields to link an image/images to show on the site?

Leeoku commented 4 years ago

I'm sure if we make each project a group icon, we can create a status for open/closed. I think keeping it as a showcase style (one icon per project with short description and general info with Github/final site link) would be best.

Joining groups is going the be the hardest. We could either leave it as "open for everyone", but I see issues cause someone will need to step up as the lead especially if they manage the repo.

phil-ociraptor commented 4 years ago

Making sure @esu2020 @pandevim @justonsky are tagged here. This is your first assignment as a team.

Once you produce the sample JSON, then the UI team will be unblocked and can pretty much start work (although they're also initially blocked by #10 )

justonsky commented 4 years ago

To build on Leeoku's suggestion, a property for tags/categories is great, though maybe instead of one string it could be an array instead (valid in the JSON spec). Additionally if there is to be a 'lead' for each project, a project_contact property may be helpful:


{
    "projectName": "SoS Website",
    "category": ["Web", "Python", "Game", "AI", "Etc."],
    "description": "This is the project that powers this website",
    "gitHubURL": "https://github.com/phil-ociraptor/sos-landing",
    "project_contact": "name of lead",  
    "contributors": {
        "first user": "linkedin.com"
    }
}

pandevim commented 4 years ago

Hi Data Team! @esu2020 @pandevim @justonsky Lets discuss this over discord: https://discord.gg/ytR2abx

justonsky commented 4 years ago

Ok -- as it stands, the JSON schema we've decided on is as follows:

Project schema:

{
    "projectName": "SoS Website",
    "category": ["Web", "Game", "AI", "Etc."],
    "techUsed": ["React", "Python", "Django", "COBOL", "FORTRAN"],
    "openToContributors": true,
    "logo": "https://thisisanexample.com/logo.png",
    "status": "In-progress",
    "shortDesc": "This is the project that powers this website",
    "longDesc": "SoS is a project that blah blah blah .... more stuff, blah",
    "projectURL": "https://github.com/phil-ociraptor/sos-landing",
    "mentor": [Person, Person],
    "team": [Person, Person, Person]
}

The properties are as follows:

projectName
category: Array of values denoting the general categories of skills involved in the project, such as web development or data science
techUsed: Array of values denoting technologies used, e.g. Python, React, Java, etc.
openToContributors: Binary value indicating whether a project is open to new contributors
logo: URL to logo image
status: Status of the project; takes on a number of limited/simplified values e.g. idea formation, in-progress and shipped so teams do not have to provide us with updates as often.
shortDesc: Short description of the project.
longDesc: Short description of the project.
projectURL: Link to the project's source code
mentor: Array of Person objects representing mentors advising the project
team: Array of Person objects representing student members of the project

Below is the Person schema:

{
    "name": "Full Name",
    "email": "something@email.com",
    "discord": "full#9999",
    "img": "somelink.aws.com",
    "url": "github/gitlab/personalwebsite"
}

The properties are as follows:

name: Name of the person
email: Person's email address
discord: Discord contact information -- Username#Discriminator
img: Profile picture
url: Person's personal website

We've settled on Airtable to store our data.

phil-ociraptor commented 4 years ago

Awesome! Ok here are some comments:

Project

Name

Given that each object is a project, we don't need to call the field projectName - it can just be name. Thought experiment: imagine working in the code, which one would you rather see

project.projectName
project.name

Enums

For the category, techUsed, and status fields, it would be good to be explicit about what the potential values can be. Essentially, imagine that they're enums, what would the values be? You've begun to do so for status, but let's nail that down.

(I know that category and techUsed might be somewhat flexible, but restricting the possible values will make our lives a little easier)

Team and Mentor fields

For the team and mentors field, I would suggest an alternate naming of members (or collaborators) and mentors. Notice that they're both plural (which suggests that the field is a collection)

I was reading up on your discussion in the discord about team[0] being special: it's the position where you can find the point person. I prefer a different approach. I believe it would be much easier to have another field on the project object called pointPerson. There are lots of things that could go wrong when "sorting" the array such that the point person is listed first.

Person

Those look great! I would say, there's a good chance we'll also want to add someone's LinkedIn. There's also a chance we'll want to hide the email and discord information of people so that they're not necessarily public on the internet.

And finally - when it comes to storing the data, let's not make a decision on that just yet. The next task I want you guys to do is:

Brainstorm multiple solutions for how to store the data
"Spike" each solution - aka someone build a prototype for each to see how hard it is (might be a 4-8 hour task). Each one of these will be its separate GitHub issue

justonsky commented 4 years ago

So after some discussion, here's the newly updated schema we're using:

Project schema:

{
    "name": "SoS Website",
    "categories": ["Web", "Game", "AI", "Etc."],
    "techUsed": ["React", "Python", "Django", "COBOL", "FORTRAN"],
    "openToContributors": true,
    "logo": "https://thisisanexample.com/logo.png",
    "status": "in-progress",
    "statusLastUpdated": "2020-06-09 (whatever timestamp)",
    "shortDesc": "This is the project that powers this website",
    "longDesc": "SoS is a project that blah blah blah .... more stuff, blah",
    "projectURL": "https://github.com/phil-ociraptor/sos-landing",
    "pointPerson": Person,
    "mentors": [Person, Person],
    "collaborators": [Person, Person, Person]
}

The properties are as follows:

name
categories: Array of values denoting the general categories of skills involved in the project, such as web development or data science
techUsed: Array of values denoting technologies used, e.g. Python, React, Java, etc.
openToContributors: Binary value indicating whether a project is open to new contributors
logo: URL to logo image
status: Status of the project; takes on one of the following values: planning, in-progress and shipped
statusLastUpdated: When did the status change
shortDesc: Short description of the project.
longDesc: Short description of the project.
projectURL: Link to the project's source code
pointPerson: Point-of-contact / communication for the project
mentors: Array of Person objects representing mentors advising the project
collaborators: Array of Person objects representing student members of the project

Initial list of values for techUsed: Python, Java, Javascript, Golang, Docker, ReactJS, NodeJS, VueJS, HTML, CSS, PostgreSQL, Angular, Flask, MongoDB

Initial list of values for categories: Android, ML, Data Science, WebApps, iOS

Below is the Person schema:

{
    "name": "Full Name",
    "email": "something@email.com",
    "discord": "full#9999",
    "linkedin": "https://linkedin.com/in/full_name",
    "twitter": "https://twitter.com/full_name",
    "img": "somelink.aws.com",
    "url": "github/gitlab/personalwebsite"
}

The properties are as follows:

name: Name of the person
email: Person's email address
discord: Discord contact information -- Username#Discriminator
linkedin: LinkedIn profile URL (if they have one, otherwise is none)
twitter: Twitter profile URL (if they have one, otherwise is none)
img: Profile picture
url: Person's personal website

pandevim commented 4 years ago

There are little semantic changes in the schema proposed after the Hasura and GraphQL Spike task (see Issue: #36). Many properties are same as @justonsky described in the above comment, some are changed. The Schema format are as follows:

type SchemaName{

    """ Property Description  """
    key: Datatype
}

Where the ! sign denote the property being required.

type Project{

    """ Unique ID (uuid) for each project """
    id: ID!

    """ Name of the project  """
    name: String!

    """ Boolean value indicating whether a project is open to new contributors """
    openToContributors: Boolean!

    """ List denoting the general categories of skills involved in the project """
    categories: [String]

    """ List denoting the general technologies like programming language used in the project """
    technologies: [String]

    """ Url to the logo image """
    img: Url

    """ Current status tag for each project (planning/in-progress/shipped) """
    status: String

    """ Timestamp value for last status update """
    statusLastUpdated: Timestamp

    """ Short summary of the project """
    summary: String!

    """ Short description of the project """
    description: String

    """ Link to the project's source code """
    codeHosting: Url!

    """ Point of contact or lead for the project team """
    pointPerson: Person!

    """ List of Mentors in project """
    mentors: [Person]!

    """ List of Collaborator in project (other than pointPerson) """
    collaborators: [Person]!

}

type Person{

    """ Unique ID (uuid) for each person """
    id: ID!

    """ Name of the project """
    name: String!

    """ Email address of the person """
    email: Email!

    """ Discord username of the person """
    discord: String

    """ Linkedin profile url of the person """
    linkedin: Url

    """ Twitter handle of the person """
    twitter: String

    """ Person image """
    img: Url

    """ Personal url (if any) """
    personal: Url

    """ Personal info that says what you do and why you do it """
    tagline: String

}

phil-ociraptor / sos-landing