DPDK CI discussions
 help / color / mirror / Atom feed
From: Adam Hassick <ahassick@iol.unh.edu>
To: ci@dpdk.org
Cc: Adam Hassick <ahassick@iol.unh.edu>
Subject: [PATCH v3 3/3] doc: Add documentation
Date: Thu, 18 Jan 2024 18:41:20 -0500	[thread overview]
Message-ID: <20240118234120.29256-4-ahassick@iol.unh.edu> (raw)
In-Reply-To: <20240118234120.29256-1-ahassick@iol.unh.edu>

Adds a new directory for storing documentation related to scripts and
other utilities in the dpdk-ci repository. Adds a new document
describing the create series artifact script.

Signed-off-by: Adam Hassick <ahassick@iol.unh.edu>
 doc/create_series_artifact.rst | 103 +++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 doc/create_series_artifact.rst

diff --git a/doc/create_series_artifact.rst b/doc/create_series_artifact.rst
new file mode 100644
index 0000000..d3a60f9
--- /dev/null
+++ b/doc/create_series_artifact.rst
@@ -0,0 +1,103 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2024 University of New Hampshire
+Create Series Artifact Script
+The create series artifact script is a small Python script for automatically applying patches and
+storing the resulting source tree in an archive.
+It gathers some information about the patches into a Java properties file for later use.
+This script is meant to be used in the context of a CI pipeline.
+Purpose and Context
+A CI pipeline needs to make branching decisions when running on a patch or series depending on the
+contents of the series or what tree it's being applied onto.
+Tests running in a pipeline should run in parallel in order to shorten the time to report results.
+This script helps to meet these needs by creating a portable archive containing the DPDK source
+tree with the patch or series applied, and some metadata about that patch or series.
+A CI pipeline and tests can use this information to make branching decisions based on the scope of
+the patch.
+Tests running in a CI pipeline can easily copy this archive and unpack it to obtain a clean
+workspace, and this can be done independently of other tests.
+At the Community Lab, the output archive from this script is stored as a Jenkins artifact.
+This is the origin of the term "artifact" in the context of this script.
+Jobs triggered downstream can then copy the artifact into their workspaces and extract them.
+This script may also serve as a reference process for applying patches that new testing labs can
+pull down and get started with.
+The script requires the following packages to be installed in the environment:
+* pygit2
+* pyyaml
+* git-pw
+Additionally, the script depends on pw_maintainers_cli and patch-parser, which are included.
+More information about configuring the script to find these dependencies can be found in the
+configuration section.
+A YAML file is used to store configuration options for this script.
+The path to one of these configuration files is a required argument of the script.
+It is responsible for storing the following information:
+* Patchwork server, project, and user token
+* URL to use when cloning the DPDK repository
+* User information for Git
+* Paths to dependent scripts and their configuration files
+When providing a server URL, make sure to include the API version in the url.
+For example: ``https://patches.dpdk.org/api/1.3/``
+An example configuration file is given in the config directory of this repository at
+If you intend to execute this script from a different working directory, other than the tools
+directory inside this repository, then you will need to change the paths in the example
+Note that if you do not provide a patchwork token in the configuration file, then the optional
+argument ``--pw-token`` on the command line becomes a required argument.
+More detail on the command line interface can be found in the next section.
+Running the Script
+Once you have a configuration file set up, running the script is simple.
+The script expects two required arguments:
+* A path to a configuration file
+* An API URL to a Series object in Patchwork
+The following block is an example of how to run the script:
+.. code-block:: console
+   ./create_series_artifact.py ../config/artifacts.yml \
+       https://patches.dpdk.org/api/1.3/series/12345
+If you choose not to provide a patchwork token in the configuration file, then you must provide
+it on the command line as follows:
+.. code-block:: console
+   ./create_series_artifact.py --pw-token <your-pw-token-here> \
+       ../config/artifacts.yml https://patches.dpdk.org/api/1.3/series/12345``
+It is not required to delete the ``dpdk`` directory that the script creates, or any of the other
+output files created by the script.
+The properties and log file will be overwritten in the next execution.
+If the ``dpdk`` directory is still present, then the script will retrieve and check out to the
+remote head rather than clone the repository again.

  parent reply	other threads:[~2024-01-18 23:42 UTC|newest]

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-01-18 23:41 [PATCH v3 0/3] Add a script to create series artifacts Adam Hassick
2024-01-18 23:41 ` [PATCH v3 1/3] tools: Add script to create artifacts Adam Hassick
2024-01-18 23:41 ` [PATCH v3 2/3] config: Add example config file Adam Hassick
2024-01-18 23:41 ` Adam Hassick [this message]
2024-02-22 19:25 ` [PATCH v3 0/3] Add a script to create series artifacts Aaron Conole

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20240118234120.29256-4-ahassick@iol.unh.edu \
    --to=ahassick@iol.unh.edu \
    --cc=ci@dpdk.org \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).