Almanac.httparchive.org: Generate the Contributors page

[rviscomi]

The Contributors page will be generated based on a JSON file with all of the contributor metadata. Required info for all contributors:

• full name
• list of teams contributed

Not required but super nice to have info:

• avatar URL (Gravatar?)
• short personal tagline ("Engineer at Company", "Web dev thoughtleader", etc)
• GitHub profile
• Twitter profile

TODO: @HTTPArchive/developers

• [x] contributors have verified their information is correct in the Contributor sheet
• [x] create a src/config/contributors.json file to organize all contributor metadata
• [ ] contributors have submitted a PR to update their metadata as needed
• [x] generate the contributors.html template based on the JSON metadata

[rviscomi]

@HTTPArchive/almanac-contributors please take a look at the Contributors sheet and leave a comment in the sheet if any of your interests are inaccurate. If you're not listed at all, please let me know in this issue.

[rviscomi]

@KJLarson this is a good first issue, do you want to give it a try? Happy to walk you through it.

[KJLarson]

I would love to give this a try!

I'm going to take a look at stuff, and then I'm sure I will have a bunch of questions.

[rviscomi]

Ok great!

[KJLarson]

I think I just created a pull request with an empty contributors.json file. I want to make sure I'm doing the collaborative GitHub thing correctly (I haven't really used it for collaborative purposes yet, just personal projects). Did I do it right?

My hope is that if I did something wrong, adding an empty file doesn't do much harm.

[rviscomi]

Looks great! I left some general feedback in the PR.

Since it's just an empty file, let's start fleshing it out. The structure of the JSON object needs to contain basic info about each contributor and group contributors into teams. Here's one approach:

global object {}

• teams {}
  
  
  
  • team_id : team info {} (key : value)
  
  
  • name
  
  
  • members []
    
    
    
    
    
    • contributor_id
    
    
    
  
  
• contributors {}
  
  
  
  • contributor_id : contributor info {} (key : value)
  
  
  • name
  
  

By only having an array of IDs for members (and not the entire contributor info) we can avoid repetition for contributors on multiple teams. An alternate approach would be to add a list of teams to the contributor info, like rviscomi: { teams: ['developers', 'analysts'] } but this would force us to look through all contributors to find out who is on a given team. My proposed approach is identical to reports.json where we have metrics and reports which are collections of metrics. Only difference here is the terminology; we have contributors and teams which are collections of contributors.

For example:

{
  "teams": {
    "developers": {
      "name": "Web Developers",
      "members": [
        "KJLarson",
        "rviscomi"
      ]
    }
  },
  "contributors": {
    "KJLarson": {
      "name": "Kari Larson"
    },
    "rviscomi": {
      "name": "Rick Viscomi"
    }
  }
}

The Contributors sheet has 8 teams: brainstorm, author, reviewer, analyst, developer, designer, translator, and editor. So here's your next task:

• [x] add the basic structure of the teams and contributors objects JSON to the file
• [x] add an entry for each team to the teams object, initially with an empty array of members
• [x] add yourself as a contributor to the developers team

[rviscomi]

Once we have the JSON file set up with some initial data (we don't need everyone in there, just one or two people to test it out) we can start integrating it with the contributors page.

For reference, see how we read the reports.json file and pass it into the template on httparchive.org. I think we'll take a similar approach here:

• [ ] create a contributors.py utility file to read the JSON object
• [ ] import the data into main.py and pass into the template
• [ ] iterate through the contributors in the template to generate the UI

Side note: One thing I want to do differently that we can optimize later is to save the contributor data in Memcache rather than global application memory.

[KJLarson]

That makes sense for organizing the data. I'll start working on building the structure of the JSON.

On contributors.html, then, would the teams and contributor information be listed separately, or can we use code to combine the lists (or make links between them)? What are your thoughts about organizing the display of the information for end users?

I'm just thinking that if I were a user looking at the list, I wouldn't take the effort to go back and forth to read about the person that corresponds to an id or figure out what team(s) a particular contributor is on. If it was combined, though, I would be much more likely to spend time on the page learning about who worked on different parts of the project.

[rviscomi]

On contributors.html, then, would the teams and contributor information be listed separately, or can we use code to combine the lists (or make links between them)? What are your thoughts about organizing the display of the information for end users?

Good questions. We're still waiting on the design to help inform the information architecture of the page, but my first thought was to list all contributors bios and under their names include a chip/badge/label (similar to how GitHub has labels on issues/PRs) for each of the teams that contributor is a member of. Then maybe stuck to the top of the page we have a way to filter by team, so you can see only its members. I made a small change to the TODO list for this part because the list of contributor IDs should be enough for us to do the filtering.

For now let's aim for generating a simple template like this for each contributor:

<h3>{{ contributor.name }}</h3>
<ul>
  <li>{{ team.name }}</li>
</ul>

We can add the filtering functionality and design in follow-up issues.

[KJLarson]

I'm working on contributors.py, the bit to add to main.py, and contributors.html, and I have a couple questions:

1. Would it be best to commit each file separately?
2. I haven't used Flask before, and know the basics of Python, so I'm doing research and looking at the example files from httparchive.org. Is it ok if I do my best and then commit the code, even if I may be totally off?

[rviscomi]

You can commit multiple files at the same time. This is preferred, especially if the changes are all related.

It's ok if you commit changes that are exploratory and you ask for feedback. We're happy to help!