How to best organize per-project files going forward?

[qobilidop]

Context

• Initialising Chirpy themed Blogs using GitHub Pages #55: We are discussing how to best organize blog post files.
  • Specifically whether to have blog post files scattered in the yearly folders or centralized in the blog folder? Initialising Chirpy themed Blogs using GitHub Pages #55 (comment)

Current status

Take a 2025 project as an example, currently it has these folder/files:

• 2025/projects/
  • gigaflow/: The project folder.
    • assests/: Images used in the project report.
    • README.md: The project report.
    • wiki.md: Used for generating a Wiki page as discussed in Could we have more stable project links to be used on the official GSoC website? #48.

My proposal

Proposal 1: Once we have project blogs, the picture gets a bit more complicated. Here's my proposal for a 2026 project:

• blog/_posts/
  • 2026-08-26-project-name.md: The project blog (also serves as the project report) as we discussed in Clarify org-level required deliverables #44.
• 2026/projects/
  • project_name/ (maybe project-name/ is better?): The project folder. Any project-related things could be stored here.
    • README.md: The project README, with links to the project blog, repo, PRs, etc.
      • Essentially replacing the wiki.md we have today. Export this README as Wiki page directly.
      • Since we no longer have the project report here, I think it's still good to have a README. The contents of wiki.md seems most fit.

Proposal 2: With project blog in its own directory, maybe having a project folder is already an overkill. Something like the following might be simpler:

• blog/_posts/
  • 2026-08-26-project-name.md: The project blog / report.
• 2026/projects/
  • project-name.md: The project README / Wiki.

Why I don't like the alternative of having blog posts scattered in the yearly folder?

• Different static site generation / blog infra might have different requirements on how its contents must be organized. If we switch to a different framework next year, the current directory structure might no longer work. So I'd prefer to have anything related to blogging be organized independently on its own, according to the blog infra's requirements.
• The blog infra we use today already have some opinions in file naming. If we want to have blog posts scattered in the yearly folder, we would have something like:
  • 2026/projects/project_name/2026-08-26-README.md

What about the existing projects?

I don't have strong opinions here. If we want to create blog posts for them retrospectively, I think it's fine to copy 2025/projects/gigaflow/REAME.md to be blog/_posts/2025-09-12-gigaflow.md.

[qobilidop]

Ping @AdarshRawat1 @Dscano @fruffy for discussion.

[Dscano]

Proposal 1 make sense to me.

[AdarshRawat1]

Proposal 1 works for me.

[Dscano]

@AdarshRawat1 @qobilidop @fruffy I think we have reached consensus for Proposal 1.

[qobilidop]

I just have another thought:

Proposal 3: Same blog post organization as Proposal 1, but with wiki pages merged into the main repo.

• blog/_posts/
  • 2026-08-26-project-name.md: The project report / blog post.
• wiki/ (maybe permalink/ is better?): Instead of using a GitHub action to copy to Wiki, is this simpler?
  • 2026-project-name.md: The project wiki. This link is expected to be permanant.
• 2026/projects/: We could still have these directories. And outside the permalink/ directory, we are free to organize / re-organize things however we want.
  • project_name/ or project-name/: Not quite sure if this is still needed. But we don't need to make a permanent decision for this.

Main considerations:

• The current wiki links are a bit unnatural to me. As an example:
  • http://github.com/p4lang/gsoc/wiki/2024%E2%80%90documentation: This link works.
  • http://github.com/p4lang/gsoc/wiki/2024-documentation: This link doesn't work.
• I realized that our main goal is to have stable links. Then how about deciding on a repo directory to serve that purpose? We could be very mindful that anything goes into that directory will have their links be stable permanently.
  • This directory's name could be further discussed. Not sure wiki/ is the best one. Some other thoughts: permalink/, stable_link/, stable_links/.

@Dscano Sorry about having more proposals after we had a consensus, but I hope it's useful discussion!

[Dscano]

I just have another thought:

Proposal 3: Same blog post organization as Proposal 1, but with wiki pages merged into the main repo.

• blog/_posts/

  • 2026-08-26-project-name.md: The project report / blog post.

• wiki/ (maybe permalink/ is better?): Instead of using a GitHub action to copy to Wiki, is this simpler?

  • 2026-project-name.md: The project wiki. This link is expected to be permanant.

• 2026/projects/: We could still have these directories. And outside the permalink/ directory, we are free to organize / re-organize things however we want.

  • project_name/ or project-name/: Not quite sure if this is still needed. But we don't need to make a permanent decision for this.

Main considerations:

• The current wiki links are a bit unnatural to me. As an example:

  • http://github.com/p4lang/gsoc/wiki/2024%E2%80%90documentation: This link works.
  • http://github.com/p4lang/gsoc/wiki/2024-documentation: This link doesn't work.

• I realized that our main goal is to have stable links. Then how about deciding on a repo directory to serve that purpose? We could be very mindful that anything goes into that directory will have their links be stable permanently.

  • This directory's name could be further discussed. Not sure wiki/ is the best one. Some other thoughts: permalink/, stable_link/, stable_links/.

@Dscano Sorry about having more proposals after we had a consensus, but I hope it's useful discussion!

Can we remove wiki/ and keep only 2026/projects/? In other words, I don’t see the value in having two folders with the same content. I looked it up, and it seems we can create permanent links to specific files: https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files. So I'm wondering if we can use the files in 2026/projects/ as permament.

[qobilidop]

Minor update: Thinking about it a bit more, I now prefer naming the directory permapage/ instead of permalink/, because the directory is hosting the permapages, while the links to those permapages become the permalinks.

First let me define some terminology:

• project permapage: A single Markdown page for a completed GSoC project, listing all other relevant links for this project (e.g. project report / blog post / PRs). The links listed on this page might evolve over time.
  • The main purpose for having this page is to serve as an indirection, in case the other links change over time. If that happens, this permapage will be updated, and people landing on this page can still easily find all the valid links.
• project permalink: A web address pointing to the project permapage. This web address is expected to be stable for a very long period of time, say at least 10 years.
  • This link is expected to be used when a GSoC contributor submit their project on the official GSoC website, where a permanent archive is kept for each project, like https://summerofcode.withgoogle.com/archive/2024/projects/u2HpJKI2.

Now my main question is, what is the best project permalink to use?

1. We've discussed previously that the GitHub Wiki is a natural permalink, once we decided a project naming scheme. And we indeed decided on that to be yyyy-project-name.
2. My follow-up thought is, do we really need to use GitHub Wiki? Or could we do something simpler? My thought is that having a special permalink/ directory in this repo is a simpler solution.

@Dscano To address your concern:

1. I'm not proposing duplicating contents between permalink/ and 2026/projects/. I think having one of them is probably enough, and I prefer permalink/.
   • In that case, I'd suggest we simply link to project permapages from 2026/README.md for example. Then there is no need to have 2026/projects/.
   • Per project assets files might be an issue. But I think there is a lot of flexibility as to how to handle that. I don't think that's a big challenge. For example, they could live with the blog posts they serve, instead of in the 2026/projects/ directory.
2. The main issue with 2026/projects/ is that this naming scheme is harder to keep permanent. We might want to re-organize things later, making it program/2026/projects/ for example.
3. I think if we want to set up permalinks, we should have a special directory dedicated to this purpose. I don't think it's a good idea to mix project permapages that require permalinks, with other docs not requiring permalinks. This decoupling also allows us to organize other docs more freely, without worrying about breaking any permalinks.
4. As you pointed out, it's possible to get permanent links to a specific file, but that link will be linked to a specific version of file like this: https://github.com/p4lang/gsoc/blob/d1a53aef3a761bdaffe65ea22e64ba3ecc9b44b7/2024/projects/documentation/README.md.
   • Link to a specific version might not be our goal. Because we might want to update that project permapage later.
   • This link is also super long and less readable.

@Dscano What do you think?

[Dscano]

Minor update: Thinking about it a bit more, I now prefer naming the directory permapage/ instead of permalink/, because the directory is hosting the permapages, while the links to those permapages become the permalinks.

First let me define some terminology:

• project permapage: A single Markdown page for a completed GSoC project, listing all other relevant links for this project (e.g. project report / blog post / PRs). The links listed on this page might evolve over time.

  • The main purpose for having this page is to serve as an indirection, in case the other links change over time. If that happens, this permapage will be updated, and people landing on this page can still easily find all the valid links.

• project permalink: A web address pointing to the project permapage. This web address is expected to be stable for a very long period of time, say at least 10 years.

  • This link is expected to be used when a GSoC contributor submit their project on the official GSoC website, where a permanent archive is kept for each project, like https://summerofcode.withgoogle.com/archive/2024/projects/u2HpJKI2.

Now my main question is, what is the best project permalink to use?

1. We've discussed previously that the GitHub Wiki is a natural permalink, once we decided a project naming scheme. And we indeed decided on that to be yyyy-project-name.
2. My follow-up thought is, do we really need to use GitHub Wiki? Or could we do something simpler? My thought is that having a special permalink/ directory in this repo is a simpler solution.

@Dscano To address your concern:

1. I'm not proposing duplicating contents between permalink/ and 2026/projects/. I think having one of them is probably enough, and I prefer permalink/.

   • In that case, I'd suggest we simply link to project permapages from 2026/README.md for example. Then there is no need to have 2026/projects/.
   • Per project assets files might be an issue. But I think there is a lot of flexibility as to how to handle that. I don't think that's a big challenge. For example, they could live with the blog posts they serve, instead of in the 2026/projects/ directory.

2. The main issue with 2026/projects/ is that this naming scheme is harder to keep permanent. We might want to re-organize things later, making it program/2026/projects/ for example.

3. I think if we want to set up permalinks, we should have a special directory dedicated to this purpose. I don't think it's a good idea to mix project permapages that require permalinks, with other docs not requiring permalinks. This decoupling also allows us to organize other docs more freely, without worrying about breaking any permalinks.

4. As you pointed out, it's possible to get permanent links to a specific file, but that link will be linked to a specific version of file like this: https://github.com/p4lang/gsoc/blob/d1a53aef3a761bdaffe65ea22e64ba3ecc9b44b7/2024/projects/documentation/README.md.

   • Link to a specific version might not be our goal. Because we might want to update that project permapage later.
   • This link is also super long and less readable.

@Dscano What do you think?

Thank you for the detailed explanation, @qobilidop, sorry, I got a bit lost in the previous message. The GitHub Wiki solution is fine, but it seems a bit too complicated. Also, I’m not fully happy with it for the reasons you pointed out.
In summary I agree with your proposal.