.. _create:

================
Create a project
================

| Creating projects from templates is the heart of QUBE.
| To learn more about our templates please visit :ref:`available_templates`.

The creation of a new project can be invoked by::

    qube create

which will guide you through the creation process of your (customized) project via prompts.
They usually follow the pattern of domain (e.g. cli, gui, ...), subdomain (if applicable, e.g. website), language (e.g. Java),
general prompts (e.g. name, email, ...) followed by template specific prompts (e.g. testing frameworks, ...).

| The template will be created at the current working directory, where QUBE has been called.

It is also possible to directly create a specific template using its handle::

    qube create --handle <HANDLE>

| After the template has been created, linting (see :ref:`lint`) is automatically performed to verify that the template creation process was successful.
| Finally, you will be asked whether or not you want to automatically push your new project to Github.

Let’s first go through the meaning of every template variable.

Shared template variables
-------------------------------

**All templates** generally use the following variables:

1. *domain*: The primary domain of the template should be used for (e.g. cli, gui or portlet).
2. *language*: The primary programming language of the template (e.g. Java, Groovy or R).
3. *project_name*: A not necessarily URL, but human friendly project name (e.g. Donut Portlet).
4. *project_slug*: A URL friendly project name (e.g. donut_portlet). This is usually autogenerated by QUBE.
5. *project_short_description*: A short description of the project, which will be displayed on Github, the README and where applicable.
6. *template_version*: The current version of the template. Autogenerated.
7. *template_handle*: The short handle of the template, which is primarily made up from the domain, (subdomain) and language (e.g. cli-java). Autogenerated.
8. *full_name*: The programmer's full name (e.g. Homer Simpson)
9. *email*: The programmer's email (e.g. homer.simpson@burnscompany.com)
10. *copyright_holder*: QBiC by default. Autogenerated.
11. *github_username*: The Github username of the programmer (e.g. HomerGithub).

Template specific variables
-----------------------------

| All templates may prompt for additional variables. You may learn more about them in their respective sections at :ref:`available_templates`.
| Please note that for all of QBiC's JVM based projects, the :code:`artifact_id` is replaced by the *project_slug*.
  Recall that all `Maven <https://maven.apache.org/>`_ based projects are identified by three fields, namely, :code:`group_id`, :code:`artifact_id` and :code:`version`, which are defined in the :code:`pom.xml` file.

Github support
-----------------

| QUBE uses `GitPython <https://gitpython.readthedocs.io/en/stable/>`_ and `PyGithub <https://pygithub.readthedocs.io/en/latest/introduction.html>`_ to automatically create a repository, add, commit and push all files.
  Moreover, issue labels and a development branch are created.
| When running :code:`qube create` for the first time, you may be prompted for your Github username, which will be saved locally in :code:`~/qube_conf.cfg`.
  Afterwards, if the answer to "Do you want to create a Github repository and push to it" was "yes", you will be prompted for your Github Personal Access Token.
| Please refer to the `official documentation <https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line>`_ on how to create one.
  QUBE only requires ``repo`` access, so you only need to tick this box. This also ensures that under no circumstances the PAT could be used to delete repositories.
| QUBE then encrypts the Personal Access Token, adds the encrypted token to the :code:`qube_conf.cfg` file and saves the key locally in a hidden place. This is safer than Github's official way, which recommends the usage of environment variables or Github Credentials, which both save the token in plaintext.
| If you create a second project using QUBE at a later stage, you will not be prompted again for your Github username, nor your Personal Access Token. Both information will automatically be extracted and loaded on the fly.
