Skip to content
CoreConnect Logo CoreConnect Logo CoreConnect

Contribute

You want to contribute to CoreConnect? Awesome! Here’s a quick guide to help you on your way.

  1. Create issues for feature/bug request via Github issues or Slack

A general overview of things to know

  • Contributing on front-end
  • Contributing on back-end
  • Contributing on documentation and business consulting

Feature requests

To be added

Back-end contributions

Every CoreConnect feature exists in 3 different domains:

  • Example project -> CoreConnect demo project that is used to showcase a particular project type (e.g. Commerce, Subscriptions, etc.)
  • CLI template -> Template project that is created from an example project and used to generate new client projects
  • Client project -> Project that was created from a CLI template and is currently being developed for a client

Project-specific code is copied and adapted within each domain, while common libraries are shared through the SDK. The way that each domain references the SDK is different, as shown in the diagram below:

flowchart BT
    example(Example project) <-. via project reference .- sdk{{SDK}}
    cli(CLI template) <-. via nuGet feed .- sdk
    client(Client project) <-. via nuGet feed .- sdk

CoreConnect Feature Types

When contributing to CoreConnect, we will distiguish between 2 different feature types (the nomenclature is open for discussion):

Seed feature

Features that are included directly on an Example project when it’s being created or updated. They are built as adaptations from an existing legacy project, Client project or developed from scratch. The seed feature development flow should look like this:

flowchart LR
    example(Example project)-->cli(CLI template)-->client(Client project)

It is first developed on the Example project, then a CLI template is updated/created with the feature as a configurable extension/plugin and ultimately Client projects are created from the CLI template (for existing Client projects the feature can be added manually or by a CLI update script - TBD). If the feature is urgently needed on an existing Client project it can be added there before updating the CLI template, but a backlog task to update the CLI template should be created and worked on as soon as possible, either by the Client project’s team or the CoreConnect team.

Client feature

Demand for these features arise as a requirement for an ongoing CoreConnect Client project and a decision is made to start development on the Client project. The client feature development flow should look like this:

flowchart LR
    client(Client project)-->example(Example project)-->cli(CLI template)

It is first developed in the Client project, then included on one (or several) Example project/s and ultimately the corresponding CLI template/s are updated with the feature as a configurable extension/plugin. If the team at the Client project doesn’t have the time/capacity to include the feature on an Example project (and/or update the CLI template), a backlog item should be created with a reference to the Client project’s implementation so the CoreConnect team can prioritize it.

CoreConnect Architecture

Please refer to the CoreConnect Architecture documentation as much as possible when developing new features. If a specific flow is supposed to always happen on the Functions project, the Gateway project should not be referencing the SDK libraries related to this flow.

SDK and project-specific code separation

The SDK should not contain any project-specific code. As a rule of thumb, anything that is configurable on an external service should not be directly added to the SDK’s code (e.g. custom fields or a specific category type from CommerceTools). The reason for this is to avoid individual projects to be constantly generating new versions of the SDK for project-specific work. This doesn’t mean that the SDK should not be updated with new features, but that those features should be generic enough to be used by all projects. For projects that fall within the same type (e.g. Commerce), project-specific code can still be shared through the CLI without disrupting the SDK development.

Notes on GraphQL versioning

GraphQL is a very powerful tool that allows us to create a flexible API that can be used by different clients. However, it is also very easy to break existing clients when making changes to the schema. For this reason, we need to be very careful when making changes to the GraphQL schema. Best practice approach is to never remove fields from the schema, but to deprecate them instead. This way, clients can be notified of the deprecation and have time to update their code before the field is removed, or even decide to keep using that field on the production project until the next refactor is planned.

Documentation contributions

Docs are found in /docs folder. There sits an Astro Starlight project, with the actual markdown files of the documentation sitting in ./src/content/docs. Based on these files, the documentation website is automatically generated.

To run locally use yarn from the /docs folder:

Terminal window
# Install packages
yarn


# Run locally on http://localhost:4321
yarn dev

Detailed instructions on how to do specific operations (like updating the GraphQL docs) is found in the readme.md inside /docs.