deploy: d2d9898

Author: j-rivero

docs/acropolis/.doctrees/environment.pickle

@@ -35,11 +35,20 @@ Before starting the release process, make sure to ask for write access to:
 1.  The Gz library intended to be released and
 2.  `gazebo-release` repository.
 
-There are some credentials needed to interact with the release
-process:
+To interact with Jenkins an API token needs to be created and stored in the
+user system:
 
- * Release token: magic sequence of characters needed while running `release.py`
-   to interact with `build.osrfoundation.org`. This should be given to Gz developers that run releases by the Infra team.
+ 1. Creating a Jenkins API token: opening https://build.osrfoundation.org/me/configure
+    the section of "API Token" shows the "Add new Token" button (alternatively a github
+    token could also be used but the Jenkins API helps to restrict the global scope
+    of the credential).
+
+ 2. The token needs to be stored in `~/.buildfarm/jenkins.ini` in the form:
+    ```
+    [https://build.osrfoundation.org]
+    username = <your-github-user>
+    password = <token created in step 1>
+    ```
 
 ## For Each Release
 
@@ -172,6 +181,17 @@ upload some Git tags ("release tags") to the source code repository.
 You will also need the token described in the [credentials
 section](#2-access-and-credentials).
 
+There are a few external dependencies for running release.py. They can be
+esily installed using virtual enviroments and pip:
+
+```
+# you can change .releasepy_venv by any directory of your preference
+python3 -m venv ~/.releasepy_venv
+. ~/.releasepy_venv/bin/activate
+cd <release-tools-dir>
+pip install .
+```
+
 **dry-run simulation mode**
 
 The `release.py` tool supports a `--dry-run` flag that allows users to
@@ -186,7 +206,7 @@ The script needs to be run from the repository with the source code (i.e., the r
 # Example of dry-run for gz-cmake3 bumped to 3.0.1
 cd gz-cmake3
 git checkout gz-cmake3
-~/release-tools/release.py gz-cmake3 3.0.1 dry-run-fake-token --dry-run
+~/release-tools/release.py gz-cmake3 3.0.1 --dry-run
 ```
 
 **release.py for stable releases**
@@ -196,11 +216,10 @@ git checkout gz-cmake3
 cd ign/gz-fooX
 git checkout ign/gz-fooX
 
-# Example gz-cmake3 bumped to 3.0.1 with jenkins_token credential
+# Example gz-cmake3 bumped to 3.0.1
 cd gz-cmake3
 git checkout gz-cmake3
-# please replace <jenkins_token> with real release token (check crendentials section)
-~/release-tools/release.py gz-cmake3 3.0.1 <jenkins_token>
+~/release-tools/release.py gz-cmake3 3.0.1
 ```
 
 **release.py for prereleases or nightlies**
@@ -210,11 +229,10 @@ to be set. The `--upload-to-repo` argument is mandatory when running
 `release.py`, and should be set to `prerelease` or `nightly`.
 
 ```bash
-# Example gz-cmake3 bumped to prerelease 3.0.0~pre1 with jenkins_token credential
+# Example gz-cmake3 bumped to prerelease 3.0.0~pre1
 cd gz-cmake3
 git checkout gz-cmake3
-# please replace <jenkins_token> with real release token (check crendentials section)
-~/release-tools/release.py gz-cmake3 3.0.0~pre1 <jenkins_token> --upload-to-repo prerelease
+~/release-tools/release.py gz-cmake3 3.0.0~pre1 --upload-to-repo prerelease
 ```
 
 Nightly invocation is generally coded in the server. The version will be
@@ -223,10 +241,8 @@ code will be uploaded, but taken directly in the binary build from the
 branch pointed by `--nightly-src-branch`.
 
 ```bash
-# Example gz-cmake3 nightly from main branch with jenkins_token credential
-# please replace <jenkins_token> with real release token (check crendentials section)
-~/release-tools/release.py gz-cmake3 3.0.0~pre1 <jenkins_token> --upload-to-repo nightly --nightly-src-branch main
-
+# Example gz-cmake3 nightly from main branch
+~/release-tools/release.py gz-cmake3 3.0.0~pre1 --upload-to-repo nightly --nightly-src-branch main
 ```
 
 **Binary version schema for prereleases and nightlies**
@@ -247,9 +263,8 @@ or the information should appear in the parameters of the Jenkins -debbuilder bu
 the first version of the sofware.
 
 ```bash
-# Example gz-cmake3 bumped from 3.0.1-1 to 3.0.1-2 with jenkins_token credential
-# please replace <jenkins_token> with real release token (check crendentials section)
-~/release-tools/release.py gz-cmake3 3.0.1 <jenkins_token> --source-tarball-uri https://osrf-distributions.s3.amazonaws.com/gz-cmake/releases/gz-cmake-3.0.1.tar.bz2 --only-bump-revision-linux -release-version 2
+# Example gz-cmake3 bumped from 3.0.1-1 to 3.0.1-2
+~/release-tools/release.py gz-cmake3 3.0.1 --source-tarball-uri https://osrf-distributions.s3.amazonaws.com/gz-cmake/releases/gz-cmake-3.0.1.tar.bz2 --only-bump-revision-linux -release-version 2
 ```
 
 ## Checking the Building Process

docs/acropolis/.doctrees/releases-instructions.doctree

@@ -479,12 +479,21 @@ <h3>2. Access and Credentials<a class="headerlink" href="#access-and-credentials
 <li><p>The Gz library intended to be released and</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">gazebo-release</span></code> repository.</p></li>
 </ol>
-<p>There are some credentials needed to interact with the release
-process:</p>
-<ul class="simple">
-<li><p>Release token: magic sequence of characters needed while running <code class="docutils literal notranslate"><span class="pre">release.py</span></code>
-to interact with <code class="docutils literal notranslate"><span class="pre">build.osrfoundation.org</span></code>. This should be given to Gz developers that run releases by the Infra team.</p></li>
-</ul>
+<p>To interact with Jenkins an API token needs to be created and stored in the
+user system:</p>
+<ol class="arabic">
+<li><p>Creating a Jenkins API token: opening <a class="reference external" href="https://build.osrfoundation.org/me/configure">https://build.osrfoundation.org/me/configure</a>
+the section of “API Token” shows the “Add new Token” button (alternatively a github
+token could also be used but the Jenkins API helps to restrict the global scope
+of the credential).</p></li>
+<li><p>The token needs to be stored in <code class="docutils literal notranslate"><span class="pre">~/.buildfarm/jenkins.ini</span></code> in the form:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">build</span><span class="o">.</span><span class="n">osrfoundation</span><span class="o">.</span><span class="n">org</span><span class="p">]</span>
+<span class="n">username</span> <span class="o">=</span> <span class="o">&lt;</span><span class="n">your</span><span class="o">-</span><span class="n">github</span><span class="o">-</span><span class="n">user</span><span class="o">&gt;</span>
+<span class="n">password</span> <span class="o">=</span> <span class="o">&lt;</span><span class="n">token</span> <span class="n">created</span> <span class="ow">in</span> <span class="n">step</span> <span class="mi">1</span><span class="o">&gt;</span>
+</pre></div>
+</div>
+</li>
+</ol>
 </section>
 </section>
 <section id="for-each-release">
@@ -616,6 +625,15 @@ <h3>4. Executing <a class="reference external" href="http://release.py">release.
 upload some Git tags (“release tags”) to the source code repository.</p>
 <p>You will also need the token described in the <a class="reference internal" href="#access-and-credentials">credentials
 section</a>.</p>
+<p>There are a few external dependencies for running <a class="reference external" href="http://release.py">release.py</a>. They can be
+esily installed using virtual enviroments and pip:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># you can change .releasepy_venv by any directory of your preference</span>
+<span class="n">python3</span> <span class="o">-</span><span class="n">m</span> <span class="n">venv</span> <span class="o">~/.</span><span class="n">releasepy_venv</span>
+<span class="o">.</span> <span class="o">~/.</span><span class="n">releasepy_venv</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span>
+<span class="n">cd</span> <span class="o">&lt;</span><span class="n">release</span><span class="o">-</span><span class="n">tools</span><span class="o">-</span><span class="nb">dir</span><span class="o">&gt;</span>
+<span class="n">pip</span> <span class="n">install</span> <span class="o">.</span>
+</pre></div>
+</div>
 <p><strong>dry-run simulation mode</strong></p>
 <p>The <code class="docutils literal notranslate"><span class="pre">release.py</span></code> tool supports a <code class="docutils literal notranslate"><span class="pre">--dry-run</span></code> flag that allows users to
 simulate releases (nothing is modified) in order to ensure that the correct
@@ -626,39 +644,36 @@ <h3>4. Executing <a class="reference external" href="http://release.py">release.
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Example of dry-run for gz-cmake3 bumped to 3.0.1</span>
 <span class="nb">cd</span><span class="w"> </span>gz-cmake3
 git<span class="w"> </span>checkout<span class="w"> </span>gz-cmake3
-~/release-tools/release.py<span class="w"> </span>gz-cmake3<span class="w"> </span><span class="m">3</span>.0.1<span class="w"> </span>dry-run-fake-token<span class="w"> </span>--dry-run
+~/release-tools/release.py<span class="w"> </span>gz-cmake3<span class="w"> </span><span class="m">3</span>.0.1<span class="w"> </span>--dry-run
 </pre></div>
 </div>
 <p><strong><a class="reference external" href="http://release.py">release.py</a> for stable releases</strong></p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Gz library named foo and major version X</span>
 <span class="nb">cd</span><span class="w"> </span>ign/gz-fooX
 git<span class="w"> </span>checkout<span class="w"> </span>ign/gz-fooX
 
-<span class="c1"># Example gz-cmake3 bumped to 3.0.1 with jenkins_token credential</span>
+<span class="c1"># Example gz-cmake3 bumped to 3.0.1</span>
 <span class="nb">cd</span><span class="w"> </span>gz-cmake3
 git<span class="w"> </span>checkout<span class="w"> </span>gz-cmake3
-<span class="c1"># please replace &lt;jenkins_token&gt; with real release token (check crendentials section)</span>
-~/release-tools/release.py<span class="w"> </span>gz-cmake3<span class="w"> </span><span class="m">3</span>.0.1<span class="w"> </span>&lt;jenkins_token&gt;
+~/release-tools/release.py<span class="w"> </span>gz-cmake3<span class="w"> </span><span class="m">3</span>.0.1
 </pre></div>
 </div>
 <p><strong><a class="reference external" href="http://release.py">release.py</a> for prereleases or nightlies</strong></p>
 <p>When releasing prereleases or nightly releases, there are some special flags
 to be set. The <code class="docutils literal notranslate"><span class="pre">--upload-to-repo</span></code> argument is mandatory when running
 <code class="docutils literal notranslate"><span class="pre">release.py</span></code>, and should be set to <code class="docutils literal notranslate"><span class="pre">prerelease</span></code> or <code class="docutils literal notranslate"><span class="pre">nightly</span></code>.</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Example gz-cmake3 bumped to prerelease 3.0.0~pre1 with jenkins_token credential</span>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Example gz-cmake3 bumped to prerelease 3.0.0~pre1</span>
 <span class="nb">cd</span><span class="w"> </span>gz-cmake3
 git<span class="w"> </span>checkout<span class="w"> </span>gz-cmake3
-<span class="c1"># please replace &lt;jenkins_token&gt; with real release token (check crendentials section)</span>
-~/release-tools/release.py<span class="w"> </span>gz-cmake3<span class="w"> </span><span class="m">3</span>.0.0~pre1<span class="w"> </span>&lt;jenkins_token&gt;<span class="w"> </span>--upload-to-repo<span class="w"> </span>prerelease
+~/release-tools/release.py<span class="w"> </span>gz-cmake3<span class="w"> </span><span class="m">3</span>.0.0~pre1<span class="w"> </span>--upload-to-repo<span class="w"> </span>prerelease
 </pre></div>
 </div>
 <p>Nightly invocation is generally coded in the server. The version will be
 taken from the last changelog entry and modified during building. No source
 code will be uploaded, but taken directly in the binary build from the
 branch pointed by <code class="docutils literal notranslate"><span class="pre">--nightly-src-branch</span></code>.</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Example gz-cmake3 nightly from main branch with jenkins_token credential</span>
-<span class="c1"># please replace &lt;jenkins_token&gt; with real release token (check crendentials section)</span>
-~/release-tools/release.py<span class="w"> </span>gz-cmake3<span class="w"> </span><span class="m">3</span>.0.0~pre1<span class="w"> </span>&lt;jenkins_token&gt;<span class="w"> </span>--upload-to-repo<span class="w"> </span>nightly<span class="w"> </span>--nightly-src-branch<span class="w"> </span>main
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Example gz-cmake3 nightly from main branch</span>
+~/release-tools/release.py<span class="w"> </span>gz-cmake3<span class="w"> </span><span class="m">3</span>.0.0~pre1<span class="w"> </span>--upload-to-repo<span class="w"> </span>nightly<span class="w"> </span>--nightly-src-branch<span class="w"> </span>main
 </pre></div>
 </div>
 <p><strong>Binary version schema for prereleases and nightlies</strong></p>
@@ -673,9 +688,8 @@ <h3>4. Executing <a class="reference external" href="http://release.py">release.
 of the software version. All the tarballs can be found at <a class="reference external" href="https://classic.gazebosim.org/distributions">https://classic.gazebosim.org/distributions</a>
 or the information should appear in the parameters of the Jenkins -debbuilder build that created
 the first version of the sofware.</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Example gz-cmake3 bumped from 3.0.1-1 to 3.0.1-2 with jenkins_token credential</span>
-<span class="c1"># please replace &lt;jenkins_token&gt; with real release token (check crendentials section)</span>
-~/release-tools/release.py<span class="w"> </span>gz-cmake3<span class="w"> </span><span class="m">3</span>.0.1<span class="w"> </span>&lt;jenkins_token&gt;<span class="w"> </span>--source-tarball-uri<span class="w"> </span>https://osrf-distributions.s3.amazonaws.com/gz-cmake/releases/gz-cmake-3.0.1.tar.bz2<span class="w"> </span>--only-bump-revision-linux<span class="w"> </span>-release-version<span class="w"> </span><span class="m">2</span>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Example gz-cmake3 bumped from 3.0.1-1 to 3.0.1-2</span>
+~/release-tools/release.py<span class="w"> </span>gz-cmake3<span class="w"> </span><span class="m">3</span>.0.1<span class="w"> </span>--source-tarball-uri<span class="w"> </span>https://osrf-distributions.s3.amazonaws.com/gz-cmake/releases/gz-cmake-3.0.1.tar.bz2<span class="w"> </span>--only-bump-revision-linux<span class="w"> </span>-release-version<span class="w"> </span><span class="m">2</span>
 </pre></div>
 </div>
 </section>

docs/acropolis/_sources/releases-instructions.md.txt

@@ -35,11 +35,20 @@ Before starting the release process, make sure to ask for write access to:
 1.  The Gz library intended to be released and
 2.  `gazebo-release` repository.
 
-There are some credentials needed to interact with the release
-process:
+To interact with Jenkins an API token needs to be created and stored in the
+user system:
 
- * Release token: magic sequence of characters needed while running `release.py`
-   to interact with `build.osrfoundation.org`. This should be given to Gz developers that run releases by the Infra team.
+ 1. Creating a Jenkins API token: opening https://build.osrfoundation.org/me/configure
+    the section of "API Token" shows the "Add new Token" button (alternatively a github
+    token could also be used but the Jenkins API helps to restrict the global scope
+    of the credential).
+
+ 2. The token needs to be stored in `~/.buildfarm/jenkins.ini` in the form:
+    ```
+    [https://build.osrfoundation.org]
+    username = <your-github-user>
+    password = <token created in step 1>
+    ```
 
 ## For Each Release
 
@@ -172,6 +181,17 @@ upload some Git tags ("release tags") to the source code repository.
 You will also need the token described in the [credentials
 section](#2-access-and-credentials).
 
+There are a few external dependencies for running release.py. They can be
+esily installed using virtual enviroments and pip:
+
+```
+# you can change .releasepy_venv by any directory of your preference
+python3 -m venv ~/.releasepy_venv
+. ~/.releasepy_venv/bin/activate
+cd <release-tools-dir>
+pip install .
+```
+
 **dry-run simulation mode**
 
 The `release.py` tool supports a `--dry-run` flag that allows users to
@@ -186,7 +206,7 @@ The script needs to be run from the repository with the source code (i.e., the r
 # Example of dry-run for gz-cmake3 bumped to 3.0.1
 cd gz-cmake3
 git checkout gz-cmake3
-~/release-tools/release.py gz-cmake3 3.0.1 dry-run-fake-token --dry-run
+~/release-tools/release.py gz-cmake3 3.0.1 --dry-run
 ```
 
 **release.py for stable releases**
@@ -196,11 +216,10 @@ git checkout gz-cmake3
 cd ign/gz-fooX
 git checkout ign/gz-fooX
 
-# Example gz-cmake3 bumped to 3.0.1 with jenkins_token credential
+# Example gz-cmake3 bumped to 3.0.1
 cd gz-cmake3
 git checkout gz-cmake3
-# please replace <jenkins_token> with real release token (check crendentials section)
-~/release-tools/release.py gz-cmake3 3.0.1 <jenkins_token>
+~/release-tools/release.py gz-cmake3 3.0.1
 ```
 
 **release.py for prereleases or nightlies**
@@ -210,11 +229,10 @@ to be set. The `--upload-to-repo` argument is mandatory when running
 `release.py`, and should be set to `prerelease` or `nightly`.
 
 ```bash
-# Example gz-cmake3 bumped to prerelease 3.0.0~pre1 with jenkins_token credential
+# Example gz-cmake3 bumped to prerelease 3.0.0~pre1
 cd gz-cmake3
 git checkout gz-cmake3
-# please replace <jenkins_token> with real release token (check crendentials section)
-~/release-tools/release.py gz-cmake3 3.0.0~pre1 <jenkins_token> --upload-to-repo prerelease
+~/release-tools/release.py gz-cmake3 3.0.0~pre1 --upload-to-repo prerelease
 ```
 
 Nightly invocation is generally coded in the server. The version will be
@@ -223,10 +241,8 @@ code will be uploaded, but taken directly in the binary build from the
 branch pointed by `--nightly-src-branch`.
 
 ```bash
-# Example gz-cmake3 nightly from main branch with jenkins_token credential
-# please replace <jenkins_token> with real release token (check crendentials section)
-~/release-tools/release.py gz-cmake3 3.0.0~pre1 <jenkins_token> --upload-to-repo nightly --nightly-src-branch main
-
+# Example gz-cmake3 nightly from main branch
+~/release-tools/release.py gz-cmake3 3.0.0~pre1 --upload-to-repo nightly --nightly-src-branch main
 ```
 
 **Binary version schema for prereleases and nightlies**
@@ -247,9 +263,8 @@ or the information should appear in the parameters of the Jenkins -debbuilder bu
 the first version of the sofware.
 
 ```bash
-# Example gz-cmake3 bumped from 3.0.1-1 to 3.0.1-2 with jenkins_token credential
-# please replace <jenkins_token> with real release token (check crendentials section)
-~/release-tools/release.py gz-cmake3 3.0.1 <jenkins_token> --source-tarball-uri https://osrf-distributions.s3.amazonaws.com/gz-cmake/releases/gz-cmake-3.0.1.tar.bz2 --only-bump-revision-linux -release-version 2
+# Example gz-cmake3 bumped from 3.0.1-1 to 3.0.1-2
+~/release-tools/release.py gz-cmake3 3.0.1 --source-tarball-uri https://osrf-distributions.s3.amazonaws.com/gz-cmake/releases/gz-cmake-3.0.1.tar.bz2 --only-bump-revision-linux -release-version 2
 ```
 
 ## Checking the Building Process