Data Structures for TC39

gistfile1.md

Data Structures

This file is for bike shedding data structures for TC39

Proposals repo data structure

Current data structure

[
  {
    "tags": ["ECMA-262", "proposal"],
    "stage": 1,
    "name": "My fantastic title",
    "link": "https://github.com/tc39/proposal-oh-so-great",
    "authors": ["Yulia Startsev", "Septs"],
    "champions": ["Septs"],
    "forks_count": 7,
    "open_issues_count": 10,
    "stargazers_count": 107,
    "created_at": "2020-09-21T14:20:14.000Z",
    "pushed_at": "2020-11-24T14:13:57.000Z"
  },
]

Proposed Data structure

This is an ideal, not necessarily what we will achieve at first. The links are place holders.

Some notes:

• we can generate the link from the proposal id, which takes the format of proposal-<name> -- from this we can also generate the spec url which is tc39.es/proposal-<name> and looks like this. This will save us from needing to process the url.
• The tags should represent information that can't be captured otherwise. I think ECMA-262 and ECMA-402 are both useful. However co-champion and specification long form names like draft are already captured in other fields and are not necessary.
• I don't know if we have an immediate use for github stars and forks. Is there a use case you have in mind?

Here is the proposed schema in json:

  {
    "tags": [string], // required inputs: "ECMA-262" or "ECMA-402". Optional inputs: "inactive" or "withdrawn"
    "stage": number, // valid inputs: 0, 1, 2, 3, 4
    "name": string,
    "id": string,
    "authors": [string], 
    "champions": [string],
    "notes": [
      {
       "date": string, // date in ISO 8601 format
       "url: string
      },
    ],
    "has-specification": bool,
    "tests": [string]
  },

And an example of what I have in mind:

[
  // Stage 0 proposal which has been presented but not advanced
  {
    "tags": ["ECMA-262"],
    "stage": 0,
    "name": "My fantastic title",
    "id": "proposal-oh-so-great",
    "authors": ["Yulia Startsev", "Septs"],
    "champions": ["Septs"],
    "notes": [
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#internationalization"
      }
    ],
    "has-specification": false,
    "tests": [],
  },
  // Stage 1 proposal 
  {
    "tags": ["ECMA-262"],
    "stage": 1,
    "name": "My fantastic title",
    "id": "proposal-oh-so-great",
    "authors": ["Yulia Startsev", "Septs"],
    "champions": ["Septs"],
    "notes": [
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#internationalization"
      }
    ],
    "has-specification": false,
    "tests": [],    
  },
  // Stage 2 proposal 
  {
    "tags": ["ECMA-262"],
    "stage": 2,
    "name": "My fantastic title",
    "id": "proposal-oh-so-great",
    "authors": ["Yulia Startsev", "Septs"],
    "champions": ["Septs"],
    "notes": [
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#internationalization"
      },
      {
       "date": "01-02-2020",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#something"
      }
    ],
    "has-specification": true,
    "tests": [],
  },
  // Stage 3 proposal 
  {
    "tags": ["ECMA-262"],
    "stage": 3,
    "name": "My fantastic title",
    "id": "proposal-oh-so-great",
    "authors": ["Yulia Startsev", "Septs"],
    "champions": ["Septs"],
    "notes": [
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#internationalization"
      },
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#something"
      },
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#something"
      }
    ],
    "has-specification": true,
    "tests": ["https://github.com/tc39/test262/issues/2909", "https://github.com/tc39/test262/issues/2908"]
  },
  // Stage 4 proposal
  {
    "tags": ["ECMA-262"],
    "stage": 4,
    "name": "My fantastic title",
    "id": "proposal-oh-so-great",
    "authors": ["Yulia Startsev", "Septs"],
    "champions": ["Septs"],
    "notes": [
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#internationalization"
      },
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#something"
      },
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#something"
      }
    ],
    "has-specification": true,
    "tests": ["https://github.com/tc39/test262/issues/2909", "https://github.com/tc39/test262/issues/2908"]
  },
  // Other types of states for proposals
  // Stage 3 proposal -- inactive
  {
    "tags": ["ECMA-262", "inactive"],
    "stage": 3,
    "name": "My fantastic title",
    "id": "proposal-oh-so-great",
    "authors": ["Yulia Startsev", "Septs"],
    "champions": ["Septs"],
    "notes": [
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#internationalization"
      },
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#something"
      },
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#something"
      }
    ],
    "has-specification": true,
    "tests": ["https://github.com/tc39/test262/issues/2909", "https://github.com/tc39/test262/issues/2908"]
  },
  // Stage 3 proposal -- withdrawn
  {
    "tags": ["ECMA-262", "withdrawn"],
    "stage": 3,
    "name": "My fantastic title",
    "id": "proposal-oh-so-great",
    "authors": ["Yulia Startsev", "Septs"],
    "champions": ["Septs"],
    "notes": [
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#internationalization"
      },
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#something"
      },
      {
       "date": "2019-09-07T15:50-04:00",
       "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#something"
      }
    ],
    "has-specification": true,
    "tests": ["https://github.com/tc39/test262/issues/2909", "https://github.com/tc39/test262/issues/2908"]
  },
]

Individual Proposal repo data structure

This is what I currently imagine. It will roughly correspond to the above but will include extra data such as example and description, which are not necessary for all aggregators, but are for the website. We may also add localization fields for the title and descriptions? what do you think?

This is a list as sometimes we merge proposals.

[{
  "tags": ["ECMA-262"],
  "stage": 3,
  "name": "My fantastic title",
  "id": "proposal-oh-so-great",
  "authors": ["Yulia Startsev", "Septs"],
  "champions": ["Septs"],
  "notes": [
    {
     "date": "2019-09-07T15:50-04:00",
     "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#internationalization"
    },
    {
     "date": "2019-09-07T15:50-04:00",
     "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#something"
    },
    {
     "date": "2019-09-07T15:50-04:00",
     "url: "https://github.com/tc39/notes/blob/master/meetings/2012-05/may-21.md#something"
    }
  ],
  "has-specification": true,
  "tests": ["https://github.com/tc39/test262/issues/2909", "https://github.com/tc39/test262/issues/2908"],
  "example": "function foo() { 'hello' }",
  "description": "This is the description",
}]