Naming conventions

Guide to naming conventions for Q-CTRL repositories, projects and packages


# Repositories

Whilst you’re free to name a repository in any way that accurately describes its contents, there are two rules that MUST be followed:

  1. The repository name MUST be the slugified version of whatever you decide to name it (e.g. Python Open Controls would be python-open-controls).
  2. If it is conceivable that the purpose of the repository may be implemented in more than one framework and/or language, the repository name MUST specify the framework or language (in that order). For example, Q-CTRL has a number of visualizer packages:
    • python-visualizer: Q-CTRL data visualization tools for Python.
    • javascript-visualizer: Q-CTRL data visualization tools for JavaScript.
    • react-visualizer: A javascript-visualizer wrapper for React.

Note: Point 2 above is typically the case for client packages (e.g. Python, Node, etc.) that implement back-end services and APIs.

# Projects

The project name is what you see as the main heading in the README file of the repository (e.g. https://github.com/qctrl/python-open-controls/blob/master/README.md).

The project name MUST be the titleized version of the repository including the organization.

Therefore, using the repository name python-open-controls as an example, the project name is Q-CTRL Python Open Controls.

# Packages

The package name is what you see as the main heading of a packages home page (e.g. https://pypi.org/project/qctrl-open-controls/).

The package name is the project name with the language implied. For example:

  • pip implies Python.
  • npm implies JavaScript.
  • gem implies Ruby.
  • etc.

Therefore, using the project name Q-CTRL Python Open Controls as an example, the package name is Q-CTRL Open Controls.

Note: For package names, whilst the language is implied, the framework is not (see examples below).

# Installs

The install name is what you use to install a package (e.g. pip install qctrl-open-controls).

The install name is the slugified version of the package name.

Therefore, using the package name Q-CTRL Open Controls as an example, the install name is qctrl-open-controls.

# Imports

The import name is what you use to import a package (e.g. import qctrlopencontrols).

The import name MAY negate the - (see PEP 8 – Style Guide for Python Code: Package and Module Names).

# Examples

# General

TypeExample
Repositoryqctrl/.github
ProjectQ-CTRL .github
PackageN/A
InstallN/A
ImportN/A
TypeExample
Repositoryqctrl/template
ProjectQ-CTRL Template
PackageN/A
InstallN/A
ImportN/A
TypeExample
Repositoryqctrl/front-end-challenge
ProjectQ-CTRL Front-end Challenge
PackageN/A
InstallN/A
ImportN/A

# Python

TypeExample
Repositoryqctrl/python
ProjectQ-CTRL Python
PackageQ-CTRL
Installpip install qctrl
Importimport qctrl
TypeExample
Repositoryqctrl/python-visualizer
ProjectQ-CTRL Python Visualizer
PackageQ-CTRL Visualizer
Installpip install qctrl-visualizer
Importimport qctrlvisualizer
TypeExample
Repositoryqctrl/django-visualizer
ProjectQ-CTRL Django Visualizer
PackageQ-CTRL Django Visualizer
Installpip install qctrl-django-visualizer
Importimport qctrldjangovisualizer

# JavaScript

TypeExample
Repositoryqctrl/javascript
ProjectQ-CTRL JavaScript
PackageQ-CTRL
Installnpm install @qctrl/qctrl
Importimport @qctrl/qctrl;
TypeExample
Repositoryqctrl/javascript-visualizer
ProjectQ-CTRL JavaScript Visualizer
PackageQ-CTRL Visualizer
Installnpm install @qctrl/visualizer
Importimport @qctrl/visualizer;
TypeExample
Repositoryqctrl/react-visualizer
ProjectQ-CTRL React Visualizer
PackageQ-CTRL React Visualizer
Installnpm install @qctrl/react-visualizer
Importimport @qctrl/react-visualizer;