It may seem obvious, but maintaining links working across every kind of web page of your project is crucial for ensuring your visitors and potential users have a good experience when learning.

Broken links can lead to frustration and may discourage users, making them leave sooner than expected.

Implement scripts to regularly check the status of links helps to promptly identify any that are breaking. Put those scripts in CIs.

Prepare backups or archived copies of linked content ensures continuity.

Notifications about broken links allow for swift corrective actions, such as requesting alternative links from authors or replacing the dead links with archived (e.g. wayback machine) versions.

This includes “meta” links in other places, such as the “website” links in git repositories.

Here’s the GitHub action we use on the awesome-gbdev list to keep links checked.

The opposite is also true, take great care in not breaking links when changing locations of your resources. Even when things are changing fast, prefer tools that allow you to host redirects and provide good internal search pages so people can always find what they were looking for.

Maintain an archive

If you’re linking to, or dealing with, open source user generated content, prepare a digital archive (e.g. a github org) forking/keeping the forks synced of such repositories. WayBack machine copies are often incomplete and binaries/past commits may be lost forever if the original author deletes them.

When hosting mirrors or historical copies, make sure that you highlight that it’s a copy, and not the upstream reference. You can also mention who is keeping this copy up in case they have additional resources (e.g. lost binaries) related to it.

This is the one we have for gbdev, the “gb-archive”.

Report an Issue

Here’s a quick checklist template:

  1. provide an example to reproduce the problem in isolation. This should include no private code. The example should be self-runnable. If a snippet is too small, create a repository.

  2. unless the problem is visual, do not include screenshots. They are not helpful.

  3. please be patient. You are probably frustrated by your problem - the maintainers are likely not aware of your workflow.

  4. be grateful for any help you are getting and follow through. The maintainers are likely giving you support for free.

[1] : Matteo Collina on Twitter

Keep CI/CD pipelines vendor-agnostic

  • Where possible, implement CI/CD steps in a “native” way (i.e. commands runnable by any shell), with GitHub Actions (or any CI/CD tool/cloud environment) functioning solely as an executor.
  • All scripts should be runnable locally with minimal changes, allowing contributors to reproduce, debug, and test workflows outside the CI environment.
  • Limit the use of third-party actions/useless templating/abstractions within GitHub workflows. Prefer straightforward scripts or commands instead of relying on complex or external GitHub-specific actions maintained by third parties.

Example:

The docker-build.yaml file in isso-comments/isso shows GitHub Action-specific “jargon” and heavy reliance on external actions. In contrast, rgbds build-container.yml accomplishes similar tasks minimizes reliance on GitHub-specific actions, prioritizing native scripting/commands.