Contributor Site


#1

Hi everyone, @whs has been working on implementing this KEP:

The TLDR is we want to put a hugo front-end on top of github.com/kubernetes/community so people can find and read the content in a friendly way instead of us sending github markdown links to each other. @whs was gracious enough to donate some of his time and we have a demo here: https://whs-dot-hk.github.io/k8sC-sigs-demo/sigs/

And we’d like to open it up for everyone to chip in. I was thinking maybe getting eyeballs on the code, and there are discussions that we need to have regarding the organization of the community repo.


#2

Hi, I have an idea of how to organize the contents of this hugo site.

I think the contents could be organized into this sections

  • Homepage
  • Guide with Getting Start
  • SIGs and WGs
  • Contributing
  • and Blog with Events and News

Because the bot is guarding the repos. We are not going to move them.

Instead, we could make a Dockerfile and run a go script and copy over all the contents we needed into hugo.

And hugo may sit in a new directory www under community.

SIGs and WGs will be the README.md now. Like the demo link quote by @castrojo above.

Contributing will be a collection of CONTRIBUTING.mds under SIGs’ or WGs’ repo.

And Blog will be a collection of other markdowns under those repos.


#3

Hey there @whs Thanks for taking the time to work on this :slight_smile:

Would you mind sharing a link to the project? Would love to take a look at it.


#4

@mrbobbytables There isn’t a single project yet. I will try to create one in this week.

Everything is scattered in places. e.g. https://whs-dot-hk.github.io/k8sC-sigs-markdowns/overview/ and the link above

A mobile responsive logo https://whs-dot-hk.github.io/k8sC-logo-demo/ etc


#5

@whs I played around with the script idea to do some of the copying / transformation on the community repo, and I think as a first pass it has some pretty positive results. Would you mind giving it a once over? It’s not golang (just bash) and only does some of the base work. It keeps everything at the root of content but I think it verifies the concept is sound. :slight_smile:

repo: https://github.com/mrbobbytables/kcommunity-site
generated site: https://stupefied-goodall-e282f7.netlify.com/

Issues encountered with importing the k/community repo:

  • Need to only copy over a subset of the content
  • Normal github and code standards usually have README.md funciton as the ‘root’, so for hugo these must be renamed to _index.md
  • Linking to documents using ‘normal’ methods as if one were coding or assuming use in github do not carry over to hugo and require correcting a bunch of targets/patterns
  • all markdown files require a header or preamble

Things discovered and are yet to be sorted out:

  • keps have a standard preamble that need to either be replaced or formatted for better usability
  • the hugo markdown renderer and github markdown renderer do not get always get along and things will not always be formatted corrected
  • linking to static content (images mostly) are not being handled and I believe will require some clean-up in the k/community repo itself

#6

I’ve asked the steering committee for a repo to we can put this in a more official place, shouldn’t take longer than a week!


#7

@mrbobbytables If I would like to move the folders started with sig- and wg- into the folder sigs and use sig-list.md as _index.md of sigs, how may I do that in gen_site.sh? Thank you.


#8

@whs It’d require changing how things are synced and using different rsync commands.

Instead of copying everything from k/community to content it’d be something like matching sig-* and wg-* while ignoring the files in the root directory and copying them to content/sigs.

After the content is synced you’ll want to move or copy over sig-list.md and rename it to _index.md.


#9

Ok here’s what we have so far:

https://stupefied-goodall-e282f7.netlify.com/

Any ideas on how to handle the list o KEPs? @joe I think you had some opinions here. I was thinking perhaps KEP at the root, and then a generated index page that took the metadata on the top of each KEP and then generated a table similar to how we do sigs.yaml, so something like:

| 001 | Kubernetes Enhancement Proposal Process | Implemented | @calebamiles @jbeda | sig-architecture | $date |

And so on. We should also probably consider listing them by status, so like, it’s clear to everyone which ones are currently drafting, in progress, in the implement stage etc.

cc @parispittman and I think @carolynvs had some ideas too.


#10

I think that is a great place to start.

In the fullness of time I think it might be cool to encode the metadata into a big JSON document and then provide ways to filter/group based on those. Filter for only the KEPs that impact SIG-architecture or those that are proposed. Javascript + JSON to build that interactivity could be sweet.


#11

Looks good.

+1 to filter. Future feature: It would be cool to filter by a status, too, which could help with picking a KEP for the community meeting.

Do you want my other suggestions/feedback here or in the GH issue? Mainly curious about how we can add the calendar for SIG meetings for the first release but have other things, too.


#12

This is great, thanks a lot for putting this together @whs and all the others who contribute. What I was wondering (and maybe it’s planned already) is: how can people find a good match? Imagine, I want to start contributing and since there’s so much choice and I’m new to the SIG responsibilities I’m having hard times deciding where to start. I could imaging a tagging system (each SIG tags itself) could be helpful? For example, I’d tag the SIG Autoscaling with, say, scaling, autscaling, resource management, metrics. WDYT?


#13

First off, the site is AMAZING! :star_struck: I’m so excited to see it coming together.

Suggestions for the KEP:

  • Instead of listing individual KEPS in the left nav, only list common filters, e.g. “Proposed”, “In-Progress”…
  • The auto-generated index page is a great idea
  • Since KEPs can be either in the SIG’s own repo, or in this one, maybe provide a list of links directly to the other KEP directories on github?

#14

I have a PoC configured with netlify where it will generate a preview on PR. If you want to give it a whirl, feel free to issue a PR against this repo: https://github.com/mrbobbytables/community. It has netlify config in the root directory and a script added hack/generate-kcommunity-site.sh that will be used by netlify to generate the hugo site based off my dev repo: https://github.com/mrbobbytables/kcommunity-site .

The only big issue I’ve encountered with this workflow is the aggressive caching from netlify can mean it won’t necessarily pull down the most recent version of the site dev repo and after an old or failed build, a manual rebuild while specifying that the cache should be cleared is needed.


#15

I don’t think we’ve thought hard about this yet, but we should definitely start thinking about this sort of metadata once we get an MVP out the door.


#16

The PoC has been moved from the original personal repo to kubernetes-sigs/contributor-site with an updated readme on getting started.

Currently netlify auto-build/preview is not configured within the main kubernetes/community repo. We have a few small details to work out before that can be completed, but that shouldn’t take too long to sort out. :slight_smile:


#17

Okay, definitely got a bit over-eager on getting something setup that way. XD
Auto-previews right now will not be configured for kubernetes/community.


#18

Blue (for SIGs?) and write


#19

As of the last of contributor experience meeting, @acontini (CNCF) says she is working on a prototype that we can give her feedback on. However she says she will need help with the actual implementation of it in CSS.

Does anyone else have strong opinions on what the site should look right? Right now the only hard constraint is we want it to look like the rest of kubernetes.io, but we want to make it clear to the user that they’re in a “developer zone” for contributing, not user-facing docs or something.