From 985e4bdec7f403a04e69ba3aa507b500ac486c13 Mon Sep 17 00:00:00 2001 From: Evgeny Konstantinov Date: Tue, 26 Jul 2016 16:24:46 +0300 Subject: [PATCH] Add preparing dev and test envs to Fuel Plugin SDK guide Change-Id: Iabb4a4ab3260dea6ada8cb7b8e9c7ac4afde3d8f --- plugindocs/fuel-plugin-sdk-guide.rst | 1 + .../create-environment.rst | 24 ++ .../create-environment/autotests.rst | 70 ++++++ .../autotests/autotests-files.rst | 26 +++ .../autotests/autotests-workflow.rst | 26 +++ .../create-environment/code-style.rst | 24 ++ .../development-requirements.rst | 13 ++ .../create-environment/launchpad-project.rst | 25 ++ .../create-environment/plugin-ci.rst | 72 ++++++ .../plugin-ci/plugin-ci-job-examples.rst | 213 ++++++++++++++++++ .../plugin-ci/plugin-ci-workflow.rst | 50 ++++ .../create-environment/plugin-repo.rst | 53 +++++ .../repository-branching.rst | 26 +++ .../repository-branching-create.rst | 30 +++ .../repository-branching-delete.rst | 22 ++ .../repository-workflow.rst | 23 ++ 16 files changed, 698 insertions(+) create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/autotests.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/autotests/autotests-files.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/autotests/autotests-workflow.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/code-style.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/development-requirements.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/launchpad-project.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci/plugin-ci-job-examples.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci/plugin-ci-workflow.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-repo.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching/repository-branching-create.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching/repository-branching-delete.rst create mode 100644 plugindocs/fuel-plugin-sdk-guide/create-environment/repository-workflow.rst diff --git a/plugindocs/fuel-plugin-sdk-guide.rst b/plugindocs/fuel-plugin-sdk-guide.rst index b6decfde6..e8996ec45 100644 --- a/plugindocs/fuel-plugin-sdk-guide.rst +++ b/plugindocs/fuel-plugin-sdk-guide.rst @@ -12,6 +12,7 @@ Fuel Plugin SDK Guide fuel-plugin-sdk-guide/introduction.rst fuel-plugin-sdk-guide/how-plugins-work.rst fuel-plugin-sdk-guide/existing-plugins.rst + fuel-plugin-sdk-guide/create-environment.rst fuel-plugin-sdk-guide/create-plugin.rst fuel-plugin-sdk-guide/requirements.rst fuel-plugin-sdk-guide/limitations.rst diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment.rst new file mode 100644 index 000000000..741f35449 --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment.rst @@ -0,0 +1,24 @@ +.. _create-environment: + +Create a development environment +================================ + +To create a development environment, you must: + +* Set up a repository and adhere to the workflow. +* Set up Continuous Integration and Continuous Deployment (CI/CD). +* Set up a testing framework. + +This section includes the following topics: + +.. toctree:: + :maxdepth: 2 + + create-environment/development-requirements.rst + create-environment/code-style.rst + create-environment/repository-workflow.rst + create-environment/repository-branching.rst + create-environment/launchpad-project.rst + create-environment/plugin-repo.rst + create-environment/plugin-ci.rst + create-environment/autotests.rst diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/autotests.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/autotests.rst new file mode 100644 index 000000000..f874c1b46 --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/autotests.rst @@ -0,0 +1,70 @@ +.. _autotests: + +Prepare a testing environment +----------------------------- + +You must configure a testing environment to ensure you plugin code quality. + +Use the following resources to download test, examples, and instructions on +how to configure a testing environment: + +* `Fuel tests `_. +* `Plugin test cases example `_. +* `Instructions on configuring an environment `_. + +Follow these additional guidelines on creating and formating your own tests: + +* When creating your own test class, you must inherit this test class from the + ``TestBasic`` class in ``base_test_case.py``, where the Fuel web client + initialization is performed. +* Each test class and method must be decorated with ``@test``. +* Each class in the test group has groups to run all test cases together + and each test case has groups for a separate run. +* Test cases have the ``depends_on`` method or ``test`` which means that this + test case does not run until the ``depends_on`` method or ``test`` is done. + +**Prepare a testing environment** + +#. Clone the ``fuel-qa`` Git repository: + + .. code-block:: console + + git clone https://github.com/stackforge/fuel-qa + +#. Activate the virtual environment: + + .. code-block:: console + + source ~/venv-nailgun-tests-2.9/bin/activate + +#. Export the Fuel ISO: + + .. code-block:: console + + export ISO_PATH=path-to-iso + +#. Go to ``fuel-qa``: + + .. code-block:: console + + cd fuel-qa/ + +#. Start the tests: + + .. code-block:: console + + ./utils/jenkins/system_tests.sh -t test -w\ + $(pwd) -j fuelweb_test -i $ISO_PATH -o --group=setup + +#. For additional information, type: + + .. code-block:: console + + ./utils/jenkins/system_tests.sh -h + +.. toctree:: + :maxdepth: 3 + :hidden: + + autotests/autotests-workflow.rst + autotests/autotests-files.rst diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/autotests/autotests-files.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/autotests/autotests-files.rst new file mode 100644 index 000000000..a85813ba9 --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/autotests/autotests-files.rst @@ -0,0 +1,26 @@ +.. _autotests-files: + +Automation test files +--------------------- + +Main files and modules: + +* ``system_tests.sh`` - The file where tests start execution. This file processes + the parameters specified from the command line and invokes ``run_tests.py``. +* ``run_tests.py`` - Used to import your test files inside this file to run your + test. +* ``settings.py`` - Contains environment variables used for environment + customization. With this file, you can set such variables as path to ISO, + nodes quantity, etc. +* ``environment.py`` - Contains methods for environment deploying, virtual machines + creation and networking, installation of Fuel on the Fuel Master node, etc. +* ``nailgun_client.py`` - Contains functionality for nailgun handlers, methods and + API that are supported by the nailgun client. The nailgun client uses the + HTTP client that located in the ``helpers`` folder. The nailgun client is + used in the Fuel web client. +* ``checkers.py`` - Has methods for the SSH client to verify nodes access. +* ``common.py`` - Has methods for OpenStack API access, instances creation, etc. +* ``decorators.py`` - Has different decorators; the most usable is + ‘’log_snapshot_on_error’’; it is recommended to use this decorator for all + tests, if any error diagnostic and environment snapshots will be created. +* ``os_actions.py`` - Has methods to work with OpenStack. \ No newline at end of file diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/autotests/autotests-workflow.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/autotests/autotests-workflow.rst new file mode 100644 index 000000000..b64bca6df --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/autotests/autotests-workflow.rst @@ -0,0 +1,26 @@ +.. _autotests-workflow: + +Automation tests execution order +-------------------------------- + +#. Base test cases are executed: these are the tests that set up environment + and install the Fuel Master node. +#. After passing these tests, snapshots are created which will be used by + the tests for creating clusters. +#. Revert to the previously created snapshots. +#. Set up the cluster and deploy it. +#. Run OSTF. + +For test execution debugging, use ``dos.py``. + +To create a snapshot, run: + +.. code-block:: console + + dos.py snapshot --snapshot-name= + +To revert a snapshot, run: + +.. code-block:: console + + dos.py revert --snapshot-name= \ No newline at end of file diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/code-style.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/code-style.rst new file mode 100644 index 000000000..ea0f0be41 --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/code-style.rst @@ -0,0 +1,24 @@ +.. _code-style: + +Install style checkers +---------------------- + +To keep the code readable, reviewable, and maintainable, adhere to the +standardized style of `Puppet `_ +and `Python `_. + +Integrate the code style checkers to your Continuous Integration (CI) workflow. + +**To install a Puppet code style checker:** + +.. code-block:: console + + gem install puppet-lint + puppet-lint --with-context ./myplugin/deployment_scripts + +**To install a Python code style checker:** + +.. code-block:: console + + pip install pep8 + pep8 --show-source --show-pep8 ./myplugin/deployment_scripts \ No newline at end of file diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/development-requirements.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/development-requirements.rst new file mode 100644 index 000000000..893c597fd --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/development-requirements.rst @@ -0,0 +1,13 @@ +.. _development-requirements: + +Development requirements +------------------------ + +Your development environment must meet the following requirements: + +* Provide DEB and RPM packages and the dependencies. For instructions + on creating packages, see `Fedora project wiki `_ + and `Ubuntu Packaging Guide `_. + +* Create Puppet manifests according to the Official OpenStack documentation. + See `Puppet in OpenStack `_. \ No newline at end of file diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/launchpad-project.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/launchpad-project.rst new file mode 100644 index 000000000..fdc309ad4 --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/launchpad-project.rst @@ -0,0 +1,25 @@ +.. _launchpad-project: + +Launchpad project +----------------- + +Launchpad is the bug tracking system that all OpenStack projects, +including Fuel and Fuel plugins, use. You must create a Launchpad +project as described in the official Launchpad documentation and +use it as a single entry point for reporting issues on your plugin +and tracking development progress. + +All Fuel plugins must follow the following conventions: + +* The project name must be in the ``fuel-plugin-`` + format. +* The project page must link to the source plugin repository and its + entry in `DriverLog `_. +* The project teams must incorporate all development team members. +* The milestones must repeat the plugin release specified in the + ``metadata.yaml file``. For example, ``1.0.0``, ``2.0.0``. + +.. seealso:: + + - `List of existing Launchpad projects `_ + - `Launchpad documentation `_ diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci.rst new file mode 100644 index 000000000..000cd78cf --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci.rst @@ -0,0 +1,72 @@ +.. _plugin-ci: + +Configure a continuous integration environment +---------------------------------------------- + +Plugin integration requires a Continuous Integration (CI) for testing +and deploying new changes. + +**To configure a continuous integration environment:** + +#. Configure Gerrit integration: + + #. Create and configure a Launchpad user to votie as a third-party + developer. See `Third Party Testing `_. + #. Add the username and public key for the Gerrit plugin configuration + in Jenkins. + #. Send an email to the openstack-dev mailing list and nominate your system + for voting permissions. + +#. Prepare the development and testing environments: + + #. Create a repository as described in :ref:`repository-workflow`. + #. Allocate enough plugin-specific testing labs. + #. Install and configure plugin-specific hardware resources. + #. Confiure testing labs. See the `Fuel development documentation `_. + +#. Configure CI: + + #. Have your own CI server. This + provides better versioning, collecting test-results, deduplicating the + same jobs, easier configuration and managing. + #. Use Jenkins with the `Jenkins Job Builder plugin `_, + which provides easy job management and storage configuration. + #. Install the Jenkins Job Builder from Git as described + below. + #. Create a pre-commit-hook to check your code: + + .. code-block:: console + + #!/bin/bash + # Save this script to /.git/hooks/pre-review + and make it executable + set -e + set -o pipefail + + find . -name '*.pp' | xargs -P1 -L1 puppet parser\ + validate --verbose + find . -name '*.pp' | xargs -P1 -L1 puppet-lint \ + --fail-on-warnings \ + --with-context \ + --with-filename \ + --no-80chars-check \ + --no-variable_scope-check \ + --no-nested_classes_or_defines-check \ + --no-autoloader_layout-check \ + --no-class_inherits_from_params_class-check \ + --no-documentation-check \ + --no-arrow_alignment-check\ + --no-case_without_default-check + find . -name '*.erb' | xargs -P1 -L1 -I '%'\ + erb -P -x -T '-' % | ruby -c + fpb --check ./ + +.. seealso:: + + - :ref:`plugin-ci-job-examples` + +.. toctree:: + :hidden: + + plugin-ci/plugin-ci-workflow.rst + plugin-ci/plugin-ci-job-examples.rst diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci/plugin-ci-job-examples.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci/plugin-ci-job-examples.rst new file mode 100644 index 000000000..bb4e9962a --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci/plugin-ci-job-examples.rst @@ -0,0 +1,213 @@ +.. _plugin-ci-job-examples: + +Job examples +------------ + +The following text is the example of Jenkins jobs at you can create +for plugins. + +* deploy-plugin.sh: + + .. code-block:: console + + #!/bin/bash + set -ex + + export SYSTEM_TESTS="${WORKSPACE}/utils/\ + jenkins/system_tests.sh" + export LOGS_DIR=${WORKSPACE}/logs/\ + ${BUILD_NUMBER} + export VENV_PATH='/home/jenkins/\ + venv-nailgun-tests-2.9' + YOUR_PLUGIN_PATH="$(ls ./*rpm)"\#Change\ + this to appropriate fuel-qa variable for your plugin + export YOUR_PLUGIN_PATH# + + sh -x "${SYSTEM_TESTS}" -w "${WORKSPACE}" -V\ + "${VENV_PATH}" -i "${ISO_PATH}" -t test -o\ + --group="${TEST_GROUP}" + +* prepare_env.sh: + + .. code-block:: console + + #!/bin/bash + set -ex + + export VENV_PATH="/home/jenkins/\ + venv-nailgun-tests-2.9" + + rm -rf "${VENV_PATH}" + + REQS_PATH="${WORKSPACE}/fuel-qa/\ + fuelweb_test/requirements.txt" + + virtualenv --system-site-packages\ + "${VENV_PATH}" + source "${VENV_PATH}/bin/activate" + pip install -r "${REQS_PATH}" --upgrade + django-admin.py syncdb --settings=devops.\ + settings --noinput + django-admin.py migrate devops --settings\ + =devops.settings --noinput + deactivate + +* syntax-build-plugin.sh: + + .. code-block:: console + + #!/bin/bash + set -ex + + find . -name '*.erb' -print 0 | xargs -0 -P1\ + -I '%' erb -P -x -T '-' % | ruby -c + find . -name '*.pp' -print 0| xargs -0 -P1\ + puppet parser validate --verbose + find . -name '*.pp' -print 0| xargs -0 -P1\ + puppet-lint \ + --fail-on-warnings \ + --with-context \ + --with-filename \ + --no-80chars-check \ + --no-variable_scope-check \ + --no-nested_classes_or_defines-check \ + --no-autoloader_layout-check \ + --no-class_inherits_from_params_class-check \ + --no-documentation-check \ + --no-arrow_alignment-check + + fpb --check ./ + fpb --build ./ + +* plugins.yaml: + + .. code-block:: ini + + - project: + name: plugin_name #Your plugin mame + path_to_fuel_iso: $PWD #Path to FuelISO + plugin_repo: plugin_repo #Your plugin repo name\ + at stackforge + email_to: emails_list #List of emails separated\ + by comma + test_group: test_group #Test group in fuel-qa for\ + deployment tests of your plugin + jobs: + - 'prepare_env' + - '{name}.build' + - '{name}.{dist}.deploy': + dist: 'centos' + - '{name}.{dist}.deploy': + dist: 'ubuntu' + + - job-template: + name: 'prepare_env' + builders: + - shell: + !include-raw-escape './builders/prepare_env.sh' + description: 'Prepare environment to testing' + logrotate: + numToKeep: 10 + parameters: + - string: + name: 'GERRIT_REFSPEC' + default: 'refs/heads/master' + scm: + - git: + branches: + - $GERRIT_BRANCH + refspec: $GERRIT_REFSPEC + url: 'https://review.openstack.org/stackforge\ + /fuel-qa' + choosing-strategy: gerrit + clean: + before: true + publishers: + - email: + notify-every-unstable-build: true + recipients: '{email_to}' + + - job-template: + name: '{name}.build' + builders: + - shell: + !include-raw-escape './builders/syntax-\ + build-plugin.sh' + description: 'Build {name} plugin\ + from fuel-plugins project' + logrotate: + numToKeep: 10 + parameters: + - string: + name: 'GERRIT_REFSPEC' + default: 'refs/heads/master' + scm: + - git: + branches: + - $GERRIT_BRANCH + name: '' + refspec: $GERRIT_REFSPEC + url: 'https://review.openstack.org/\ + stackforge/{plugin_repo}' + choosing-strategy: gerrit + clean: + before: true + triggers: + - gerrit: + trigger-on: + - patchset-created-event #Trigger\ + plugin build for every gerrit patchset + projects: + - project-compare-type: 'PLAIN' + project-pattern: '{plugin_repo}' + branches: + - branch-compare-type: 'ANT' + branch-pattern: '**' + silent: true + server-name: 'review.openstack.org' + publishers: + - archive: + artifacts: '*.rpm' + - email: + notify-every-unstable-build: true + recipients: '{email_to}' + + - job-template: + name: '{name}.{dist}.deploy' + builders: + - copyartifact: + project: '{name}.build' + which-build: last-successful + - inject: + properties-content: | + OPENSTACK_RELEASE={dist} + TEST_GROUP={test_group} + ISO_PATH={path_to_fuel_iso} + - shell: + !include-raw-escape './builders/\ + deploy-plugin.sh' + description: 'fuel-qa system test for {name}' + logrotate: + numToKeep: 10 + parameters: + - string: + name: 'GERRIT_REFSPEC' + default: 'refs/heads/master' + scm: + - git: + branches: + - $GERRIT_BRANCH + refspec: $GERRIT_REFSPEC + url: 'https://review.openstack.org/\ + stackforge/fuel-qa' + choosing-strategy: gerrit + clean: + before: true + wipe-workspace: false + publishers: + - archive: + artifacts: 'logs/$BUILD_NUMBER/*' + - email: + notify-every-unstable-build: true + recipients: '{email_to}' diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci/plugin-ci-workflow.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci/plugin-ci-workflow.rst new file mode 100644 index 000000000..99ae4fb63 --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-ci/plugin-ci-workflow.rst @@ -0,0 +1,50 @@ +.. _plugin-ci-workflow: + +CI workflow +----------- + +The Fuel developers team recommends that you follow this CI workflow: + +#. Prepare labs and start or update the lab: + + * Download the ISO from `Fuel CI `_. + Depending on the Fuel version specified in plugin’s requirements, + Jenkins downloads the released ISO and/or the currently developed + and passed BVT test on core CI. + + * Deploy the downloaded ISO and prepare the required labs + for testing using the ``fuel-dev`` and ``fuel-qa`` repositories: + + .. code-block:: console + + $ fuel-main/utils/jenkins/system_tests -t test -j\ + dis_fuelweb_test -i (path to downloaded Fuel-ISO)\ + -o --group=setup -V ${VIRTUAL_ENV} -k + + * Create or restore the required empty VMs from snapshots. + +#. A Gerrit review job starts building your plugin. + See `Gerrit workflow `_. + + #. Use a preconfigured `Gerrit Trigger `_ + to start your job after a new Gerrit patch arrives. + #. Run a code syntax checker and unit tests according to the instructions + from `Testing `_. + #. Run a Puppet linter. See `Puppet OpenStack `_. + #. Build the plugin. + #. Trigger the plugin testing. + +#. Vote on the Gerrit patch page and add review the result in the comment + using Gerrit Trigger. +#. Test the plugin: + + #. Install the plugin. + #. Configure the environment. + #. Deploy the environment with the inactive plugin. + #. Run the OSTF tests. + +#. Run plugin-specific functional tests to check that the current plugin + version provides expected functionality. +#. Publish the resulting aggregated logs to the log storage. + + You can do this by archiving logs. diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-repo.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-repo.rst new file mode 100644 index 000000000..4f2b4db7b --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/plugin-repo.rst @@ -0,0 +1,53 @@ +.. _plugin-repo: + +Request an OpenStack repository +------------------------------- + +When you are ready to move your plugin project to a repository +in the OpenStack namespace, request a repository in the Fuel for +OpenStack Launchpad project. + +Before requesting an OpenStack repository, verify that you have +the following: + +* An account in Launchpad. +* A list of members to whom you want to grant the core reviewer + status in your plugin project. +* A list of members to whom you want to grant the the release developer + status. + +**To request an OpenStack repository:** + +#. Ensure you are registered with the following resources: +#. Go to the `Fuel project in Launchpad `_. +#. Click :guilabel:`Report a bug`. +#. In :guilabel:`Summary`, type in ``Create a Fuel Plugin project in + /Openstack``. +#. In the :guilabel:`Further information` field put the following details: + + * Plugin name. + * Plugin functionality overview. + * Developer's contact information (email, skype, etc.). + + Ensure that all members to who you want to grant the core reviewer rights + are registered at + ``__. Otherwise, they cannot be granted the + core review status. + + * List of core review developers with contact information: name, email in + ``__. These developers will merge changes. + * List of release developers with contact information: name, email in + ``__. These developers will create release + branches and tags in the repository. + `Example `__. + +#. Click :guilabel:`Extra`. +#. In :guilabel:`Tags`, type ``devops``. + + When the Launchpad ticket is marked ``Fix Committed`` or ``Fix Released``, + your repository is created. + +#. Fill your repository with the required files: + + * Your plugin code. See :ref:`describe-plugin`. + * Documentation. diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching.rst new file mode 100644 index 000000000..50369ad19 --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching.rst @@ -0,0 +1,26 @@ +.. _repository-branching: + +Managing Git branches +--------------------- + +To track the release cycle efficiently, branch your project or use tags. + +Difference between a branch and a tag: + +* A tag represents a version of a particular branch at a moment in time. +* A branch represents a separate thread of development that may run + concurrently with other development efforts on the same code base. + Changes to a branch may eventually be merged back into another branch + to unify them. + +Examples: + +* For a tagging example, see the `VPNaaS plugin `_ repository. +* For a branching example, see the `LMA plugin `_ repository. + +.. toctree:: + :maxdepth: 3 + :hidden: + + repository-branching/repository-branching-create.rst + repository-branching/repository-branching-delete.rst diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching/repository-branching-create.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching/repository-branching-create.rst new file mode 100644 index 000000000..ae4e631a7 --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching/repository-branching-create.rst @@ -0,0 +1,30 @@ +.. _repository-branching-create: + +Create a branch +--------------- + +There are two ways to create a branch, using CLI or using the web UI. + +**To create a branch using CLI:** + +.. code-block:: console + + git push : + +Where: + +* ```` is the name of your Gerrit remote or the full remote URL. +* ```` is the refname; this can be a branch or something else. +* ```` is the name of the branch you want created. + +**To create a branch using the web UI:** + +#. Ensure you are a core reviewer. +#. Go to `review.openstack.org `_. +#. In the :guilabel:`Project` menu, click :guilabel:`Branches`. +#. Enter a new branch name and click the :guilabel:`Create branch` button. + You can leave the :guilabel:`Initial revision` field blank. + +.. seealso:: + + - :ref:`repository-branching-delete` \ No newline at end of file diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching/repository-branching-delete.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching/repository-branching-delete.rst new file mode 100644 index 000000000..c4f3d31ce --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-branching/repository-branching-delete.rst @@ -0,0 +1,22 @@ +.. _repository-branching-delete: + +Delete a branch +--------------- + +You may need to delete a branch in OpenStack if you no longer need the branch, +merged that branch with other branch, or dropped the development of the branch + +**To delete a branch:** + +#. Select from the following options: + + * Contact the openstack-infra core team via mailing list. + See `example request `_. + * Report a bug in the `Fuel project `_ and assign + it to Fuel DevOps team. + * Request in #openstack-infra IRC channel on freenode.net. You can contact + the following core members there: fungi, clarkb, jeblair, pleia2. + +.. seealso:: + + - :ref:`repository-branching-create` \ No newline at end of file diff --git a/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-workflow.rst b/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-workflow.rst new file mode 100644 index 000000000..54686c4e8 --- /dev/null +++ b/plugindocs/fuel-plugin-sdk-guide/create-environment/repository-workflow.rst @@ -0,0 +1,23 @@ +.. _repository-workflow: + +Repository workflow +------------------- + +As a plugin developer, your repository workflow must be the following: + +#. Start your plugin development in your own repository open to public. + The repository can be any public Git hosting; for example, GitHub. + +#. When you are ready to put your developed plugin project to the official + repository in the OpenStack namespace, you need to do the following: + + * Have your code reviewed by the `Fuel team `_. + You can also request a review in the #fuel-dev channel in IRC. + * Plan to set up a CI for the plugin. See :ref:`plugin-ci`. + * Confirm that you are going to support the plugin for more than one + version of Fuel. + * Confirm that you are releasing your plugin code under the Apache 2.0 + license. + * Confirm your plugin code has no binary files. + * Request repository creation in the OpenStack namespace. + See :ref:`plugin-repo`. \ No newline at end of file