Contributing

Ways to contribute

cpp.social is a community-maintained project - your help is required to keep this site up to date and ensure we're listing the resources people actually care about.

If you notice missing resources, wrong descriptions and other mistakes or have general feedback on how to improve the usability to this site, please do reach out. While we prefer it where possible, you do not have to submit a pull request for your suggested changes - it is also possible to let us know through an issue.

For content submissions, please check for duplicates first and make sure the suggested content fulfills our content requirements.

What we list

Content must be relevant to C++ developers and have a stable public page.

• Tutorials, guides, and other learning resources must be free to access in full, without a purchase or subscription. Books are of course exempt from this.
• Books, blogs, and YouTube channels must contain substantive human-created work. Purely AI-generated publications are not eligible.
• Tooling must have real users beyond personal experiments or toy projects. Include available evidence of use, such as public projects that depend on them.

Submit a pull request

To locally build the site, you will need Python 3.13 or newer and Node.js 24 (the version used in CI). The rest of the tooling can be installed by invoking make install.

1. Read the relevant guide below and edit the relevant file(s). Follow a nearby entry's structure and use only supported fields.
2. Optional: If the entry needs fetched metadata, you may run the guide's updater command for that entry (do inspect the output to ensure there's no unrelated changes!).
3. Run make build and check the affected page under build/.
4. Open a pull request against cppsocial/site. Describe the change and explain why it was made.

For code changes, also run make check-format, make lint, and make test. If formatting fails, use the matching make format-* command shown in the failure message.

Generated files

Add content through the source files named in these guides, not by editing generated files under data/.

Hand-maintained exceptions are covered in the Packages and Content maintenance guides.

Pick the destination

Add a card

Add a record under the existing cards list:

- title: Example Tool
  path: https://example.org/
  description: Short factual explanation of its use in C++
  metadata:
    License: MIT
  links:
    - {label: Documentation, path: https://example.org/docs/}
    - {label: Source, path: https://github.com/example/tool}

Requirements

• Provide a concise title and the canonical HTTPS path
• Explain the entry's relevance to C++ in a short, factual description
• Check that the entry is public and not already listed; for active projects, look for recent releases or development
• For a project or tool, show that it has real users and is relevant to C++ developers
• Add metadata and secondary links only when they help someone evaluate or use the entry
• Use labels already established in that section
• Follow the shared URL, description, and YAML rules in the Style guide

Icons and hidden entries

Omit icon to discover the site's favicon automatically. Set icon: null when no icon should be displayed. Use an explicit HTTPS image URL only when favicon discovery gives the wrong result.

Check the result

Run make build, open the affected page under build/, and check the card at narrow and wide widths. Confirm that every link works and that the description does not duplicate the title.

Chat, forum, and Q&A communities

Add chat communities to the cards list in content/communities/im.yaml and forums or Q&A sites to the cards list in content/communities/forums.yaml. Every community_id must be unique and must not change after publication.

- community_id: example-community
  metadata_source: {source: web, key: 'https://example.org/community/'}
  title: Example C++ Community
  platform: forum
  path: https://example.org/community/
  description: Public forum for C++ library design and implementation questions

Allowed platform values are discord, slack, irc, reddit, and forum. Allowed metadata sources are discord, web, reddit, and stackoverflow. For web, the key is the canonical page URL; for Reddit, it is the subreddit name without r/. For Stack Overflow, use the encoded tag c%2B%2B as the key.

Communities must be public, active, and substantially about C++. Use a direct community URL and a description of its audience or focus.

Discord

Copy the code after discord.gg/ from the community's invite, or create an invite with expiry set to Never if you have permission. Use that code as both the URL suffix and metadata key:

- community_id: example-discord
  metadata_source: {source: discord, key: Ab3dE9xYz2}
  title: Example C++ Discord
  platform: discord
  path: https://discord.gg/Ab3dE9xYz2
  description: Public chat for C++ developers working on embedded systems

The PR check uses Discord's API to check that the invite resolves, has no expiry, and is not the server's vanity code. Open it to confirm that it leads to the intended community.

Check the result

For a new community, fetch only its metadata, then build:

make communities ID=example-community
make build

For Meetup groups, run make events, then make build and inspect /events/. This refreshes all configured event feeds; leave unrelated changes out of the PR. See Generated files for when to include updater output.

Hosting

The site is published at cpp.social through GitHub Pages from cppsocial/site. The deployment workflow also triggers a separate mirror repository.

To manually redeploy, rerun the build-deploy.yaml workflow.

Pull request previews

Pull request previews are opt-in because the preview builds code from the pull request. After reviewing the change, a repository collaborator with write access can comment /preview on the pull request. The workflow records the current pull request commit, refreshes only metadata selected by changed curated records, builds without repository secrets, and deploys the resulting artifact to https://pr-<number>--cppsocial.netlify.app.

The deploy uses the netlify-preview environment, never github-pages. On success, the workflow comments with the preview URL and Netlify CLI output.

Tokens & Mirror

The content of the primary site is mirrored onto cppsocial.github.io via Github actions. This is a separate repository (and just republishes the build artifacts from the primary repo) to prevent Github from redirecting to cpp.social.

To facilitate this, there's two PATs in place: - GH_IO_MIRROR gives cppsocial/site R/W access to actions in cppsocial/cppsocial.github.io. This is used to start the mirroring action after a successful site built. - GH_IO_SOURCE gives cppsocial/cppsocial.github.io read access to cppsocial/site's action artifacts

These might need updating every now and then.

Adding Maintainers/Curators

Checklist:

• Add new maintainer or curator to MAINTAINERS.md
• Invite them to the cppsocial organization here
• Add them to the appropriate teams (always add Maintainers to the Curator team as well!)