Data Structures for TC39

gistfile1.txt

# 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](https://tc39.es/proposal-class-fields/). 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?

```
{
  "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",
}
```