Building a New Feature in CC Search

CC Search is an open source project and we welcome community involvement. Our active sprint, and backlog are public and we maintain a set of GitHub issues that we could use help with.

We also want to enable you - our community members - to build features that would be useful to you, regardless of where those features are on our roadmap. However, we want to make sure any new feature fits into our product vision for CC Search, and we are a small team with limited bandwidth.

If you do want to build a new feature, and we would love it if you did, all we ask is that you follow the process outlined in this document to ensure a smooth experience for everyone involved.

Step 0

Evaluate Process

Figure out if you need to follow this process.

Please note that this process is only for adding significant features that require product input or infrastructural work from CC staff. If you are just fixing a bug or making an improvement to existing features, follow our much simpler guidelines for contributing code. If you're not sure what category your proposed change falls under, ask us on GitHub or via our chat/mailing list.

Examples that do not need to follow this process:

  • Any issue marked "help wanted".
  • Improving the user experience or fixing bugs related to existing features (example 1, example 2)
    • Reasoning: It does not change the user experience in any significant way and does not require approval.
  • Adding automated tests to the code
    • Reasoning: It is not a user facing change and does not remove or change existing functionality.

Examples that should follow this process:

  • Adding a new content type (such as audio files) to CC Search
    • Reasoning: It changes the fundamental structure of CC Search and requires significant product input and infrastructural work from CC staff.
  • Adding a new filter to the search results page
    • Reasoning: It is user facing and requires some product input and may require infrastructural work to collect the data that the search results will filter on.

Step 1

GitHub Issue

Describe the feature on GitHub.

Look through our issues to see if there is already a GitHub issue describing the feature you want to build. If none exists, create one on the cccatalog-frontend repository (which holds the code for CC Search) using the "Feature request" template.

On this GitHub issue, add a comment describing the feature you want to build and why you think it would be a good addition to CC Search. Add as much detail as you can.

Step 2

CC Response

Wait for a CC staff member to respond.

Someone on the CC Search staff will aim to review your comments within five business days and get back to you with one of these responses:

  • Ask for more information
  • Preliminarily approve the feature
  • Reject the feature with an explanation and close the issue

If at any time it has been more than five business days and you haven't received a response to your last message, please comment on the issue or contact us elsewhere. Note that staff availability is limited during certain parts of the year, such as our annual CC Global Summit and our bi-annual staff retreats.

Once your feature has been preliminarily approved, proceed to Step 3.

Step 3


Plan your work.

Create an implementation plan with the list of changes you'll need to make to implement your feature.

Keep in mind that CC Search heavily depends on the CC Catalog API (docs, code) and the CC Catalog data (code). You may need to make changes in one of those projects; you cannot add or modify data in CC Search if it is not provided by the API, and you cannot provide data through the API if it is not collected in the CC Catalog. Some tasks (such as setting up infrastructure or ingesting new data into the CC Catalog) can only be performed by CC staff; please highlight those dependencies. You don't have to do this step on your own; asking us questions or soliciting our opinions on aspects of your plan are encouraged.

Once your implementation plan is ready, update the GitHub issue and wait for a staff member to respond (per Step 2). If your work does not depend on any work by CC Staff, we will either approve your plan or provide feedback and ask you to make some changes. If your plan does depend on work by CC staff, we may reject it if it is infeasible for us to do that work in a reasonable time, otherwise we will provide feedback or approve it with a rough timeline of when we can complete the work that blocks you.

Once your plan has been approved, proceed to the next applicable step.

Step 4


Get Design and UX approved (if applicable).

If your feature involves user-facing changes, please run these by us, either through wireframes or high fidelity mockups. We will either approve your design or provide feedback and ask you to make some changes.

Once your design has been approved, proceed to Step 5.

Step 5


Wait for CC staff to resolve dependencies (if applicable).

If your feature depends on work that only CC staff can do, please wait for us to do that work. If you can start working on other parts of the feature in parallel, you may go ahead.

Step 6


Write your code.

At this point, CC staff and you should be on the same page about how the feature will be implemented and what it will look like. Here's where you get to actually implement it!

Commit early and often, follow our pull request and code guidelines, and write tests!

Step 7

Code Review

Get feedback via code review.

Once your pull request is ready, someone on CC staff will review your code and provide feedback. Once all feedback has been resolved, your code will be merged into the main branch of the repository.

You may have to do Steps 4-7 for multiple codebases in some cases, e.g. if your work includes both the CC Catalog API and CC Search, the API work will have to be done before the CC Search work that depends on it.

Step 8


Get feedback via live testing.

Once your code is merged, it will be deployed to the staging server and tested manually (in addition to the comprehensive automated tests that you've already written). We may need to run some changes by our product counsel. This may produce an additional round of feedback for you to address.

Step 9


The feature is live!

Once any feedback from Step 8 is resolved, we will merge your code into the stable branch and deploy it to production. Congrats, your feature is live!