Naming conventions
Guide to naming conventions for Q-CTRL repositories, projects, and packages
Repositories
The name of a repository SHOULD accurately describe its contents, and it MUST follow the following rules.
Standard repositories
The repository name MUST be composed of the following elements, in this order:
1. Product : The name of the company product that relates to the repository. Ignore if the repository doesn’t relate to a single product.
2. Purpose : The main purpose of the repository. Ignore if the repository implements the entirety of a product. This can be the name of the package the repository releases or the service it provides. You can include the language or framework in which the repository is implemented : (1) if it’s conceivable the purpose of the repository will be implemented in more than one framework or language or : (2) if it’s crucial for the repository’s purpose.
The repository name MUST be the slugified version of the relevant elements in this order: [product]-[purpose]. See some examples of names for standard repositories in the following table:
| Product | Purpose | Repository name |
|---|---|---|
| Black Opal | black-opal |
|
| Open Controls | open-controls |
|
| Boulder Opal | Python Client | boulder-opal-python-client |
| Fire Opal | Core | fire-opal-core |
| Fire Opal | Python Commons | fire-opal-python-commons |
| Billing Service | billing-service |
|
| Docs | docs |
|
| Jobs | jobs |
|
| Sphinx Theme | sphinx-theme |
|
| Python QUA Adapter | python-qua-adapter |
|
| Python Visualizer | python-visualizer |
|
| JavaScript Visualizer | javascript-visualizer |
|
| React Visualizer | react-visualizer |
Research repositories
Research repositories MUST be the slugified repository’s purpose, prefixed by research-. For example, research-system-identification.
Projects
The project name is what you see as the main heading in the README file of the repository (for example, https://github.com/qctrl/notebooks/blob/master/.github/README.md).
The project name MUST be the titleized version of the repository name, preceded by the organization.
See some examples of project names in the following table:
| Repository name | Project name |
|---|---|
black-opal |
Q-CTRL Black Opal |
open-controls |
Q-CTRL Open Controls |
boulder-opal-python-commons |
Q-CTRL Boulder Opal Python Commons |
boulder-opal-python-client |
Q-CTRL Boulder Opal Python Client |
fire-opal-core |
Q-CTRL Fire Opal Core |
billing-service |
Q-CTRL Billing Service |
docs |
Q-CTRL Docs |
sphinx-theme |
Q-CTRL Sphinx Theme |
python-qua-adapter |
Q-CTRL Python QUA Adapter |
javascript-visualizer |
Q-CTRL JavaScript Visualizer |
research-notebooks |
Q-CTRL Research Notebooks |
Packages
For repositories that release a package, the package name is what you see as the main heading of the package’s home page. For example, https://pypi.org/project/qctrl-open-controls/ for a Python package or https://www.npmjs.com/package/@qctrl/visualizer for a JavaScript package.
The package name is the project name with the language implied. For example:
-
pipor “Python package” implies Python. -
npmor “Node package” implies JavaScript. -
gemor “RubyGem” implies Ruby. - etc.
Note: Whilst the language is implied, the framework is not.
If the project name includes a product name (that is, from the Products tab of the organization website), ignore the organization name in the package name.
See some examples of package names in the following table:
| Project name | Package name |
|---|---|
| Q-CTRL Open Controls | Q-CTRL Open Controls |
| Q-CTRL Boulder Opal Python Commons | Boulder Opal Commons |
| Q-CTRL Boulder Opal Python Client | Boulder Opal Client |
| Q-CTRL Sphinx Theme | Q-CTRL Sphinx Theme |
| Q-CTRL Javascript Visualizer | Q-CTRL Visualizer |
| Q-CTRL Python QUA Adapter | Q-CTRL QUA Adapter |
| Q-CTRL Python Visualizer | Q-CTRL Visualizer |
| Q-CTRL React Visualizer | Q-CTRL React Visualizer |
Installs and imports
The install name is what you use to install a package. For example, pip install qctrl-open-controls for Python or npm install @qctrl/react-visualizer for JavaScript.
The import name is what you use to import a package. For example, import qctrlopencontrols for Python or import @qctrl/react-visualizer; for JavaScript.
Python packages
For Python packages, the install name is the slugified version of the package name. The import name is the install name, removing dashes (-) (see PEP 8 – Style Guide for Python Code: Package and Module Names). If the package is an API client, client is left out of the install and import names. If the package is an adapter, adapter is left out of the install and import names.
See some examples of install and import names for Python packages in the following table:
| Package name | Install name | Import name |
|---|---|---|
| Q-CTRL Open Controls | qctrl-open-controls |
qctrlopencontrols |
| Boulder Opal Commons | boulder-opal-commons |
boulderopalcommons |
| Fire Opal Client | fire-opal |
fireopal |
| Q-CTRL Sphinx Theme | qctrl-sphinx-theme |
qctrlsphinxtheme |
| Q-CTRL QUA Adapter | qctrl-qua |
qctrlqua |
| Q-CTRL Visualizer | qctrl-visualizer |
qctrlvisualizer |
JavaScript packages
For JavaScript packages, both the install and import names are the slugified version of the package name, removing qctrl- if it contains it, and placing it in the @qctrl organization namespace. If the package is an API client, client is left out of the install and import names.
See some examples of install and import names for JavaScript packages in the following table:
| Package name | Install and import name |
|---|---|
| Fire Opal Client | @qctrl/fire-opal |
| Q-CTRL Visualizer | @qctrl/visualizer |
| Q-CTRL React Visualizer | @qctrl/react-visualizer |
Examples
General
| Type | Example |
|---|---|
| Repository | qctrl/.github |
| Project | Q-CTRL .github |
| Package | N/A |
| Install | N/A |
| Import | N/A |
| Type | Example |
|---|---|
| Repository | qctrl/template |
| Project | Q-CTRL Template |
| Package | N/A |
| Install | N/A |
| Import | N/A |
| Type | Example |
|---|---|
| Repository | qctrl/front-end-challenge |
| Project | Q-CTRL Front-end Challenge |
| Package | N/A |
| Install | N/A |
| Import | N/A |
Python packages
| Type | Example |
|---|---|
| Repository | qctrl/fire-opal-python-client |
| Project | Q-CTRL Fire Opal Python Client |
| Package | Fire Opal Client |
| Install | pip install fire-opal |
| Import | import fireopal |
| Type | Example |
|---|---|
| Repository | qctrl/fire-opal-core |
| Project | Q-CTRL Fire Opal Core |
| Package | Fire Opal Core |
| Install | pip install fire-opal-core |
| Import | import fireopalcore |
| Type | Example |
|---|---|
| Repository | qctrl/python-visualizer |
| Project | Q-CTRL Python Visualizer |
| Package | Q-CTRL Visualizer |
| Install | pip install qctrl-visualizer |
| Import | import qctrlvisualizer |
| Type | Example |
|---|---|
| Repository | qctrl/django-visualizer |
| Project | Q-CTRL Django Visualizer |
| Package | Q-CTRL Django Visualizer |
| Install | pip install qctrl-django-visualizer |
| Import | import qctrldjangovisualizer |
| Type | Example |
|---|---|
| Repository | qctrl/sphinx-theme |
| Project | Q-CTRL Sphinx Theme |
| Package | Q-CTRL Sphinx Theme |
| Install | pip install qctrl-sphinx-theme |
| Import | import qctrlsphinxtheme |
JavaScript packages
| Type | Example |
|---|---|
| Repository | qctrl/boulder-opal-javascript-client |
| Project | Q-CTRL Boulder Opal JavaScript Client |
| Package | Boulder Opal Client |
| Install | npm install @qctrl/boulder-opal |
| Import | import @qctrl/boulder-opal; |
| Type | Example |
|---|---|
| Repository | qctrl/javascript-visualizer |
| Project | Q-CTRL JavaScript Visualizer |
| Package | Q-CTRL Visualizer |
| Install | npm install @qctrl/visualizer |
| Import | import @qctrl/visualizer; |
| Type | Example |
|---|---|
| Repository | qctrl/react-visualizer |
| Project | Q-CTRL React Visualizer |
| Package | Q-CTRL React Visualizer |
| Install | npm install @qctrl/react-visualizer |
| Import | import @qctrl/react-visualizer; |