Skip to content

Contributing to Code Thesaurus

An image showing all of the contributors to Code Thesaurus so far

Some of Code Thesaurus's contributors to date! Made with contributors-img.

Welcome!

Code Thesaurus has come as far as it has thanks to around 100 individuals that have taken their time to help make this a super useful tool! If that includes you, thank you!

We welcome the contributions from people of any development experience level and of any open source experience level. We've worked hard to ensure the docs are easy to read, accurately describe the steps needed to take, and is easy to install, run, and contribute to!

Read on to learn more about the contribution process.

Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socioeconomic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

You agree to follow our Code of Conduct while working on the project and/or being a part of any related communities. You can read that here.

Hacktoberfest

Code Thesaurus grew out of @geekygirlsarah building it over Hacktoberfests 2018-2023. She's loved working with the community each year to on the project, and so Code Thesaurus plans to opt in to future events.

Learn more about the event on the Hacktoberfest website.

Check Out the Project

First, head over to https://codethesaur.us to see how the site currently works.

You can also install and run it yourself by reading over the Installation section of these docs.

You can also look at the About section to learn more about the history, how the site is designed and developed, and how the core thesaurus files are created.

What Can I Do?

Some of the types of work we need here include:

  • Working on site features or bugs filed as Issues on the project.
  • Adding programming language information to the thesaurus data files (issues are tagged by language).
  • Adding new programming languages. Those won't have issues, but follow the directions on the Thesaurus section of the docs to add them, then make a pull request.
  • Working on documentation (this site). You can see if there's any available issues to work on.
  • File any bugs, incorrect information, or missing information you find on GitHub.
  • Or propose new ideas! Many people have offered ideas on how to improve the site or the matching algorithm and are now integrate into the site.

Claiming An Issue

If you find an issue you want to work on, please claim it first.

First, review the full issue as I try to make them as detailed as possible. If you wish to claim it, leave a comment indicating so. I can then add you as the assignee in GitHub.

If you take more than a couple of weeks to work on it, I may send you a message asking about the status. This is mostly to see how you're doing and if you have questions. We understand people get busy and that life happens, so if you still want to work on it but are just slow, we understand!

If we reach out and don't hear back from you, we may un-assign you to that issue. This opens it up for others to work on. If you're unassigned but still want to work on it, let us know and we can reassign you.

Thesaurus Data Updates

The ultimate goal of Code Thesaurus is to provide the best polyglot developer reference tool to any and all developers, regardless of language they code in. To that end, we'll need contributions not just to the website framework but to the actual thesaurus data files too.

We try to make issues for all the information we know is missing, but there's no way to create issues for everything. If you see your favorite language isn't on the site, you're welcome to add an issue to start working on it, or just go ahead and start adding it and make a pull request for it.

For more information on how to fill in missing language data, check out the Thesaurus section of these docs.

Reporting Bugs or Issues

Did you find a bug? Great! Make sure it's not already reported on our Issues page. If it's not, please open up a New Issue and add it so I can look it over. (If it already exists, I may close it.)

Please make your issue as detailed as possible! Add in the page or URL where it happened, what you were doing when the error occurred, or any other details important to the issue. Any steps you include to recreate it help me out a lot. I may contact you to try to get more details if I can't replicate it.

From Issue to PR

Think you can tackle an issue? Great!

Prepare Your Fork

  1. Fork the repo so you have your own copy of it.
  2. Create a new branch. You can name it whatever you want, but I'd recommend something descriptive, like issue-123-fix-string-exception.

Make Your Changes

  1. Make your changes! I suggest committing early and often.
  2. Make sure you test the changes on your own computer. See the Installation section of the docs for directions on how to run it. Once they work reliably, you're ready to open a pull request.

Open a Pull Request

  1. Create a new pull request. The template should walk you through all the information you need to include. If you don't fill it out, the issue may be closed for being invalid or spam.

Use of AI Tools

We're happy for you to use AI tools to help you contribute — a lot of our contributors do, and they can be a great way to speed up work or learn something new. But AI-generated changes have to meet the same bar as any other contribution:

  • Follow the project's conventions and docs — the structure, naming, and style, including the thesaurus data rules. Code examples must genuinely work in that language; don't let an AI invent syntax or fake a feature that should be marked "not-implemented": true.
  • Follow the PR template — including the "AI bots used" section, telling us what you used and how. (Please actually review the changes before submitting.)
  • Be tested — run the unit tests and the data-validation commands, and make sure the GitHub Actions checks pass.

Low-effort AI pull requests — unchecked dumps of generated code that ignore the conventions, skip the template, or aren't tested — will be closed or marked as spam. If we misjudge one of yours, reach out and we'll take another look.

Review and Merge

  1. GitHub Actions will run to test the changes and to validate data files. If you have contributed before, it should spin up a review deploy automatically.
  2. If any of the GitHub Actions fail, click on the details link next to it to see what went wrong. You will have to make changes for it to pass before your code can get merged in.
  3. I'll review it and leave any comments for things that may need to change. Any comments that are made aren't because your code is bad but more information about how this code may work with other parts of the project or ways the user might interact with it. Don't take it as a fault but instead as considerations to help you improve what you do have.
  4. Finally, we'll merge it in! Changes usually go into effect 1-2 minutes after merging.

Note: Due to the prolific spam at past Hacktoberfests, your PR may get marked as invalid or spam if it appears not to follow directions or appears to just be trying to get easy PRs for the swag. If it's mistakenly marked as invalid/spam, please reach out so I can correct it.

Adding or Revising Documentation

I want Code Thesaurus to be easy-to-use for anyone regardless of their experience level. That requires good documentation of all facets of the project. I welcome any additional changes or suggestions on what to change or how to evolve the documentation so it's helpful for people to understand the technical side of the site.

What About Cosmetic Patches?

Issues marked with a frontend tag are open to having the cosmetic changes fixed. If there are typos or other issues, you are welcome to try to correct those. However, frivolous PRs for unnecessary changes may be marked as invalid or spam.

Have Questions or Problems?

Please feel free to reach out! You can:

Happy Developing!