feat: turn data/projects into a markdown file

[BryanPan342]

thoughts on turning this into markdown? might be easier to add to, but also not necessary

opensource/data/projects.ts

Lines 6 to 17 in 938f3a7

	{
	name: 'Buffer Buffet',
	description: 'All of our projects are open-source! Literally, all of them.',
	repo: 'https://github.com/uclaacm/buffer-buffet',
	link: 'https://bufferbuffet.uclaacm.com/',
	image: '/projects/buffer-buffet.png',
	alt: 'buffer buffet landing splash',
	lang: Language.JS,
	tech: [
	'react', 'x86',
	],
	},

[mattxwang]

By markdown, do you mean making the entire thing some sort of Jekyll/Hugo-style front matter? Or just changing some of the descriptions to use markdown instead of strings?

Definitely open to making this more parseable, since this quarter I'll probably be going a bit ham in adding all of ACM's stuff.

[matthewcn56]

Instead of manually adding in a JSON object of projects, why don't we use the Github Developer APIs to programatically generate the list of projects to display? This would also enforce good convention by making our open-source projects properly detail their projects by adding in topics, links to their project, and more.

[mattxwang]

Instead of manually adding in a JSON object of projects, why don't we use the Github Developer APIs to programatically generate the list of projects to display? This would also enforce good convention by making our open-source projects properly detail their projects by adding in topics, links to their project, and more.

Not a bad idea, but a couple of caveats:

1. Above all, people do not write documentation, and they do not write their documentation consistently. this is less of a technical problem and more of a large-scale bureaucracy problem. If you have suggestions, let me know what you think.
2. Not all of our projects live under the uclaacm org; AI has their own org, some stuff is under me, etc.
3. Where would they list a long-form description? An image? The related technologies (this could be tags, I guess)? I imagine we would still have to add more metadata and that will have to live somewhere.
4. How would we demarcate a project as "work in progress"? Incomplete, abandoned, etc. What about projects that aren't really "open-source", but code dumps? Or asset/writeup dumps?

If you feel like you have an even partial solution for this, I would suggest to go for it! Even if it's not perfect, I'd love to see a more human-parseable description of our projects :)

[BryanPan342]

@mattxwang

what you could do is tag projects as acm/opensource and then have all open source projects have a file like opensource.yml and essentially u can just filter for repos with the tag and only render projects that have the right configurations…

even sexier would be to create an npm package to lint a config file to make sure all the configurations are up to date

[matthewcn56]

1. Above all, people do not write documentation, and they do not write their documentation consistently. this is less of a technical problem and more of a large-scale bureaucracy problem. If you have suggestions, let me know what you think.

While it's true that not everyone writes documentation, I think that filling in repository fields that are made available through GitHub APIs: like descriptions of projects, links to deployments or websites detailing the project if they are made, descriptions, and more are good practice and imo enforcing that these fields are properly filled out can only be a good thing.

2. Not all of our projects live under the uclaacm org; AI has their own org, some stuff is under me, etc.

I personally think that ACM's projects should all be contained within the @uclaacm organization. However, we can combine octokit along with JSON/YAML/Markdown files for extra projects, or can also use octokit within acm AI's org as well to get their projects.

For extra metadata, I like Bryan's idea of adding in a .yml files specific for our projects, but we should try to fit in as much as we can into normal github repository information, like using the image from each repository's social media image preview and more.

[mattxwang]

Right, I think my point is more that it will be very hard to get people within ACM to add descriptions, tags, etc. to the existing (and old) repositories. I don't think this should be a barrier for you getting started - just something to keep in mind! If you go ahead with this approach, you could also make posts in the Slack, announcements at all-hands, etc. to make sure these things happen!

As for containing things within organizations - it's hard to move things since then it breaks permalinks, and for AI in particular they rely on the subdomain for their org for their website (i.e. uclaacmai.github.io). We could engineer a move over for them soon, though it would probably have to happen over the summer when no critical work is happening.

Overall, feel free to steer this in the direction that you're interested in; very down for you to take ownership for the project and see it get better!