[Starlingx-discuss] Full process to update/add documentation pages
Hello, I follow the documentation instruction to add more documentation. I have created my page locally and I have two questions : - how do I get a gerrit login to push my documentation review ? - how can I check locally, before pushing, how my page will look ? Finally I must say that, to my little brain" the paragraph 'Closing Out a Bug or Story' is less than clear. I had look at the tox.ini file (only 1 exists at the directory root) and add no clue where I should add the requested information. -- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
On 12/09/2019 10:49, Dominig ar Foll (Intel Open Source) wrote:
- how can I check locally, before pushing, how my page will look ?
When I try to use the documented process to build my page locally, I have the following error.
tox -e ~/starlingx/git/docs/ ERROR: unknown environment '/home/dominig/starlingx/git/docs/'
-- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
On 2019-09-12 10:56:13 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote: [...]
When I try to use the documented process to build my page locally, I have the following error.
tox -e ~/starlingx/git/docs/ ERROR: unknown environment '/home/dominig/starlingx/git/docs/'
The correct command should be `tox -e docs` (here the -e option specifies a testenv named "docs" corresponding to a [testenv:docs] section in the repository's https://opendev.org/starlingx/docs/src/branch/master/tox.ini file). -- Jeremy Stanley
On 12/09/2019 15:55, Jeremy Stanley wrote:
On 2019-09-12 10:56:13 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote: [...] The correct command should be `tox -e docs` (here the -e option specifies a testenv named "docs" corresponding to a [testenv:docs] section in the repository's https://opendev.org/starlingx/docs/src/branch/master/tox.ini file). Sorry no more luck. dominig@dominig-t480:~/starlingx/git/docs> tox -e docs docs create: /home/dominig/starlingx/git/docs/.tox/docs ERROR: invocation failed (exit code 1), logfile: /home/dominig/starlingx/git/docs/.tox/docs/log/docs-0.log ERROR: actionid: docs msg: getenv cmdargs: ['/usr/bin/python3', '-m', 'virtualenv', '--python', '/usr/bin/python3', 'docs']
Already using interpreter /usr/bin/python3 Using base prefix '/usr' New python executable in /home/dominig/starlingx/git/docs/.tox/docs/bin/python3 Also creating executable in /home/dominig/starlingx/git/docs/.tox/docs/bin/python Installing setuptools, pip, wheel... Complete output from command /home/dominig/starli...tox/docs/bin/python3 - setuptools pip wheel: Traceback (most recent call last): File "<stdin>", line 9, in <module> File "/usr/lib64/python3.6/pkgutil.py", line 624, in get_data importlib._bootstrap._load(spec)) File "<frozen importlib._bootstrap>", line 684, in _load File "<frozen importlib._bootstrap>", line 656, in _load_unlocked File "<frozen importlib._bootstrap>", line 626, in _load_backward_compatible File "/usr/lib/python3.6/site-packages/virtualenv_support/pip-19.1.1-py2.py3-none-any.whl/pip/_vendor/requests/__init__.py", line 94, in <module> File "<frozen importlib._bootstrap>", line 971, in _find_and_load File "<frozen importlib._bootstrap>", line 955, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 656, in _load_unlocked File "<frozen importlib._bootstrap>", line 626, in _load_backward_compatible File "/usr/lib/python3.6/site-packages/virtualenv_support/pip-19.1.1-py2.py3-none-any.whl/pip/_internal/__init__.py", line 40, in <module> File "<frozen importlib._bootstrap>", line 971, in _find_and_load File "<frozen importlib._bootstrap>", line 955, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 656, in _load_unlocked File "<frozen importlib._bootstrap>", line 626, in _load_backward_compatible File "/usr/lib/python3.6/site-packages/virtualenv_support/pip-19.1.1-py2.py3-none-any.whl/pip/_internal/cli/autocompletion.py", line 8, in <module> File "<frozen importlib._bootstrap>", line 971, in _find_and_load File "<frozen importlib._bootstrap>", line 955, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 656, in _load_unlocked File "<frozen importlib._bootstrap>", line 626, in _load_backward_compatible File "/usr/lib/python3.6/site-packages/virtualenv_support/pip-19.1.1-py2.py3-none-any.whl/pip/_internal/cli/main_parser.py", line 12, in <module> File "<frozen importlib._bootstrap>", line 971, in _find_and_load File "<frozen importlib._bootstrap>", line 955, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 656, in _load_unlocked File "<frozen importlib._bootstrap>", line 626, in _load_backward_compatible File "/usr/lib/python3.6/site-packages/virtualenv_support/pip-19.1.1-py2.py3-none-any.whl/pip/_internal/commands/__init__.py", line 6, in <module> File "<frozen importlib._bootstrap>", line 971, in _find_and_load File "<frozen importlib._bootstrap>", line 955, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 656, in _load_unlocked File "<frozen importlib._bootstrap>", line 626, in _load_backward_compatible File "/usr/lib/python3.6/site-packages/virtualenv_support/pip-19.1.1-py2.py3-none-any.whl/pip/_internal/commands/completion.py", line 6, in <module> File "<frozen importlib._bootstrap>", line 971, in _find_and_load File "<frozen importlib._bootstrap>", line 955, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 656, in _load_unlocked File "<frozen importlib._bootstrap>", line 626, in _load_backward_compatible File "/usr/lib/python3.6/site-packages/virtualenv_support/pip-19.1.1-py2.py3-none-any.whl/pip/_internal/cli/base_command.py", line 20, in <module> File "<frozen importlib._bootstrap>", line 971, in _find_and_load File "<frozen importlib._bootstrap>", line 955, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 656, in _load_unlocked File "<frozen importlib._bootstrap>", line 626, in _load_backward_compatible File "/usr/lib/python3.6/site-packages/virtualenv_support/pip-19.1.1-py2.py3-none-any.whl/pip/_internal/download.py", line 368, in <module> AttributeError: module 'pip._vendor.requests' has no attribute 'Session' ---------------------------------------- ...Installing setuptools, pip, wheel...done. Traceback (most recent call last): File "/usr/lib64/python3.6/runpy.py", line 193, in _run_module_as_main "__main__", mod_spec) File "/usr/lib64/python3.6/runpy.py", line 85, in _run_code exec(code, run_globals) File "/usr/lib/python3.6/site-packages/virtualenv.py", line 2328, in <module> main() File "/usr/lib/python3.6/site-packages/virtualenv.py", line 713, in main symlink=options.symlink) File "/usr/lib/python3.6/site-packages/virtualenv.py", line 945, in create_environment download=download, File "/usr/lib/python3.6/site-packages/virtualenv.py", line 901, in install_wheel call_subprocess(cmd, show_stdout=False, extra_env=env, stdin=SCRIPT) File "/usr/lib/python3.6/site-packages/virtualenv.py", line 797, in call_subprocess % (cmd_desc, proc.returncode)) OSError: Command /home/dominig/starli...tox/docs/bin/python3 - setuptools pip wheel failed with error code 1 ERROR: Error creating virtualenv. Note that some special characters (e.g. ':' and unicode symbols) in paths are not supported by virtualenv. Error details: InvocationError('/usr/bin/python3 -m virtualenv --python /usr/bin/python3 docs (see /home/dominig/starlingx/git/docs/.tox/docs/log/docs-0.log)', 1) __________________________________________________________________________________________ summary __________________________________________________________________________________________ ERROR: docs: Error creating virtualenv. Note that some special characters (e.g. ':' and unicode symbols) in paths are not supported by virtualenv. Error details: InvocationError('/usr/bin/python3 -m virtualenv --python /usr/bin/python3 docs (see /home/dominig/starlingx/git/docs/.tox/docs/log/docs-0.log)', 1) -- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
On 2019-09-12 16:00:44 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote: [...]
AttributeError: module 'pip._vendor.requests' has no attribute 'Session' [...]
This looks like a corrupt/mismatched existing virtualenv tox is trying to reuse: https://github.com/pypa/virtualenv/issues/1213 You might try forcing tox to recreate the virtualenv from scratch with the -r option like `tox -r -e docs` and see if it gets any farther. -- Jeremy Stanley
On 2019-09-12 20:50:35 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote: [...]
Is there any simpler way to check how a page would look before commiting it in Gerrrit ? [...]
"Simpler" is a relative term. Since tox is being used here to abstract away building a dedicated Python virtual environment, installing documentation build dependencies and running Sphinx commands to convert reStructuredText markup into HTML content, you would basically need to perform the same steps yourself instead (make sure your current working directory is the top-level directory of the Git repository's worktree): virtualenv -p python3 mydocs mydocs/bin/pip install -c https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraint... -r doc/requirements.txt mydocs/bin/sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html The commands above were inferred from the tox.ini file in that project. Resulting content should appear in the doc/build/html directory. Of course, I fully expect you'll see virtualenv break there the same way it does when tox tries to call it, but it's worth a try. I'm unable to reproduce the error on my systems so it's tough to be certain. As far as troubleshooting what's gone sideways with your tox setup, what version of virtualenv are you using? I see it's calling pip 19.1.1 according to the output you quoted, but it doesn't seem to mention the virtualenv version. Some additional Web searching suggests this error can be a result of using a too-new version of pip with a too-old version of virtualenv, so if that seems to be the case you might see if you can either upgrade the version of virtualenv to something as recent as the version of pip (seems https://pypi.org/project/pip/#history says it was released in May of this year so you might try virtualenv>=16.6), or downgrade the version of pip to something contemporary with the version of virtualenv you've got. Another possibility is that this stems from mixing a distro package of one with a PyPI package of the other. Linux distributions often "debundle" or strip out "vendored" copies of libraries like the requests package in pip's _vendor tree, and instead expect applications to import it from an equivalent distro-provided package as a dependency to reduce duplication. Knowing how you set up your development environment might be useful information in trying to guess at the reason tox is basically broken for you. -- Jeremy Stanley
On 2019. Sep 12., at 21:36, Jeremy Stanley <fungi@yuggoth.org> wrote:
On 2019-09-12 20:50:35 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote: [...]
Is there any simpler way to check how a page would look before commiting it in Gerrrit ? [...]
"Simpler" is a relative term. Since tox is being used here to abstract away building a dedicated Python virtual environment, installing documentation build dependencies and running Sphinx commands to convert reStructuredText markup into HTML content, you would basically need to perform the same steps yourself instead (make sure your current working directory is the top-level directory of the Git repository's worktree):
virtualenv -p python3 mydocs
mydocs/bin/pip install -c https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraint... -r doc/requirements.txt
mydocs/bin/sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
The commands above were inferred from the tox.ini file in that project. Resulting content should appear in the doc/build/html directory. Of course, I fully expect you'll see virtualenv break there the same way it does when tox tries to call it, but it's worth a try. I'm unable to reproduce the error on my systems so it's tough to be certain.
[…] I usually run the tests in a virtual machine to avoid having anything going wrong with my laptop. I can confirm that on a fresh Ubuntu 16.04 after installing tox and cloning the StarlingX docs repo the ‘tox -e docs’ command works like a charm. Thanks, Ildikó
Sorry but if we want to motivate people to write more documentation we need to find a simpler way. To write docs we need to be able to at least check the display of a page before committing in a simple way. If the environment is complex to reproduce and to debug, then we should have, at least, somewhere a web page creation service. How reviewer will check that was is proposed is OK and looks fine ? It's a serious issue that needs to be addressed with urgency. Dominig On 12/09/2019 21:48, Ildiko Vancsa wrote:
On 2019. Sep 12., at 21:36, Jeremy Stanley <fungi@yuggoth.org> wrote:
On 2019-09-12 20:50:35 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote: [...]
Is there any simpler way to check how a page would look before commiting it in Gerrrit ? [...]
"Simpler" is a relative term. Since tox is being used here to abstract away building a dedicated Python virtual environment, installing documentation build dependencies and running Sphinx commands to convert reStructuredText markup into HTML content, you would basically need to perform the same steps yourself instead (make sure your current working directory is the top-level directory of the Git repository's worktree):
virtualenv -p python3 mydocs
mydocs/bin/pip install -c https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraint... -r doc/requirements.txt
mydocs/bin/sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
The commands above were inferred from the tox.ini file in that project. Resulting content should appear in the doc/build/html directory. Of course, I fully expect you'll see virtualenv break there the same way it does when tox tries to call it, but it's worth a try. I'm unable to reproduce the error on my systems so it's tough to be certain. […]
I usually run the tests in a virtual machine to avoid having anything going wrong with my laptop. I can confirm that on a fresh Ubuntu 16.04 after installing tox and cloning the StarlingX docs repo the ‘tox -e docs’ command works like a charm.
Thanks, Ildikó
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
-- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
If run tox against your local doc tree, it generates all the html files for you and you can point your browser at them and see exactly how the files will render in production. brucej -----Original Message----- From: Dominig ar Foll (Intel Open Source) [mailto:dominig.arfoll@fridu.net] Sent: Thursday, September 12, 2019 1:29 PM To: starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] ERROR: unknown environment with tox -e when bulding doc locally Sorry but if we want to motivate people to write more documentation we need to find a simpler way. To write docs we need to be able to at least check the display of a page before committing in a simple way. If the environment is complex to reproduce and to debug, then we should have, at least, somewhere a web page creation service. How reviewer will check that was is proposed is OK and looks fine ? It's a serious issue that needs to be addressed with urgency. Dominig On 12/09/2019 21:48, Ildiko Vancsa wrote:
On 2019. Sep 12., at 21:36, Jeremy Stanley <fungi@yuggoth.org> wrote:
On 2019-09-12 20:50:35 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote: [...]
Is there any simpler way to check how a page would look before commiting it in Gerrrit ? [...]
"Simpler" is a relative term. Since tox is being used here to abstract away building a dedicated Python virtual environment, installing documentation build dependencies and running Sphinx commands to convert reStructuredText markup into HTML content, you would basically need to perform the same steps yourself instead (make sure your current working directory is the top-level directory of the Git repository's worktree):
virtualenv -p python3 mydocs
mydocs/bin/pip install -c https://git.openstack.org/cgit/openstack/requirements/plain/upper-con straints.txt -r doc/requirements.txt
mydocs/bin/sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
The commands above were inferred from the tox.ini file in that project. Resulting content should appear in the doc/build/html directory. Of course, I fully expect you'll see virtualenv break there the same way it does when tox tries to call it, but it's worth a try. I'm unable to reproduce the error on my systems so it's tough to be certain. […]
I usually run the tests in a virtual machine to avoid having anything going wrong with my laptop. I can confirm that on a fresh Ubuntu 16.04 after installing tox and cloning the StarlingX docs repo the ‘tox -e docs’ command works like a charm.
Thanks, Ildikó
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
-- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
On 2019-09-12 22:29:04 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote:
but if we want to motivate people to write more documentation we need to find a simpler way. To write docs we need to be able to at least check the display of a page before committing in a simple way.
If the environment is complex to reproduce and to debug, then we should have, at least, somewhere a web page creation service. How reviewer will check that was is proposed is OK and looks fine ?
It's a serious issue that needs to be addressed with urgency. [...]
It's an environment optimized for embedding documentation in and extracting documentation from software written in the Python programming language. StarlingX borrowed its documentation workflow from OpenStack, whose software is written almost entirely in Python (the OpenStack community wanted to make sure that its developers didn't have any excuse to avoid writing and updating documentation). With this, of course, comes the complexity of getting a Python software development environment going, which I can understand might seem odd or challenging to folks who are not computer programmers, or perhaps who focus on other languages are are disinterested in getting acquainted with Python language ecosystem conventions and norms). Regardless of what tooling is used to manage documentation, I expect that the basics of making it possible to write in a simple markup language, being able to propose and review changes to documentation prior to publication, and recording changes under annotated revision control are still beneficial, as is the ability to take advantage of continuous integration and deployment automation to reject proposed changes for common errors or style deviations and to publish them automatically on approval. The current solution meets those needs, but they could still be met by using different documentation build tooling too as long as someone writes Zuul jobs to install and run that instead of python+tox+virtualenv+sphinx. -- Jeremy Stanley
On 2019-09-12 10:49:21 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote: [...]
how do I get a gerrit login to push my documentation review? [...]
The starlingx/docs repository, like most of StarlingX's Git repositories, is hosted in OpenDev. For now, the Developer's Guide in the OpenDev Infrastructure Manual can be found here: https://docs.openstack.org/infra/manual/developers.html It covers topics such as Gerrit account setup. -- Jeremy Stanley
On 12/09/2019 15:52, Jeremy Stanley wrote:
https://docs.openstack.org/infra/manual/developers.html
It covers topics such as Gerrit account setup.
Thanks that bit is helpful. But my review still fails. dominig@dominig-t480:~/starlingx/git/docs/doc/source/developer_resources> git review -t "initial creation Doc page Navigate Git Code story/2005184" Creating a git remote called 'gerrit' that maps to: ssh://dominig@review.opendev.org:29418/starlingx/docs.git Your change was committed before the commit hook was installed. Amending the commit to add a gerrit change id. error: src refspec creation does not match any. error: src refspec Doc does not match any. error: src refspec page does not match any. error: src refspec Navigate does not match any. error: src refspec Git does not match any. error: src refspec Code does not match any. error: src refspec story/2005184 does not match any. error: failed to push some refs to 'ssh://dominig@review.opendev.org:29418/starlingx/docs.git' My changes are not rocket science (see diff bellow) but still did not make it :-( The pending review is not visible in Gerrit. -- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre diff --git a/doc/source/developer_resources/navigate_source_code.rst b/doc/source/developer_resources/navigate_source_code.rst index 7a14dfe..3d597f6 100644 --- a/doc/source/developer_resources/navigate_source_code.rst +++ b/doc/source/developer_resources/navigate_source_code.rst @@ -2,9 +2,61 @@ How to navigate the StarlingX source code ========================================= -This topic is coming soon. +The StartlingX code is kept in various git directories. In order to simplify the downloading process of keeping your local copy up to date, StartlingX project provides Android type repo manifests which can be followed by the repo tool. + + +^^^^^^^^^^^^^^^^^ +Tools required +^^^^^^^^^^^^^^^^^ + + On top of your prefer text editor you will need two tools to download the StartlingX source code: + - git (certainly available from your prefered Linux distro) + - Android repo tool. A simple python script that is installed manually. + + To install git, follow the instruction to install git package from your Linux distro. + + To install the required Android Repo Tool in the Linux host system. Follow + the steps in the `Installing + Repo <https://source.android.com/setup/build/downloading#installing-repo>` + + You will find more details on the repo tool `here <https://source.android.com/setup/develop/repo>` + + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Initial download of StartlingX code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Create a *starlingx* workspace directory on your system. + Best practices dictate creating the workspace directory + in your $HOME directory: + + .. code:: sh + + $ mkdir -p $HOME/starlingx/ + +#. Use the repo tool to create a local clone of the manifest + Git repository based on the "master" branch: + + .. code:: sh + + $ cd $MY_REPO_ROOT_DIR + $ repo init -u https://opendev.org/starlingx/manifest -m default.xml + +#. Synchronize the repository: + + .. code:: sh + + $ repo sync -j`nproc` + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Keeping in sync with StartlingX upstream code code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + .. code:: sh + + $ repo sync -j`nproc` + -Linked Story does not yet exist. .. `Linked Story <https://storyboard.openstack.org/#!/story/2005184>`__ ~
A bit of a shot in the dark but I suspect it has to do with the spaces in the " initial creation Doc page Navigate Git Code story" string
-----Original Message----- From: Dominig ar Foll (Intel Open Source) <dominig.arfoll@fridu.net> Sent: Thursday, September 12, 2019 4:15 PM To: starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Full process to update/add documentation pages (gerrit review push issue)
On 12/09/2019 15:52, Jeremy Stanley wrote:
https://docs.openstack.org/infra/manual/developers.html
It covers topics such as Gerrit account setup.
Thanks that bit is helpful.
But my review still fails. dominig@dominig- t480:~/starlingx/git/docs/doc/source/developer_resources> git review -t "initial creation Doc page Navigate Git Code story/2005184" Creating a git remote called 'gerrit' that maps to: ssh://dominig@review.opendev.org:29418/starlingx/docs.git Your change was committed before the commit hook was installed. Amending the commit to add a gerrit change id. error: src refspec creation does not match any. error: src refspec Doc does not match any. error: src refspec page does not match any. error: src refspec Navigate does not match any. error: src refspec Git does not match any. error: src refspec Code does not match any. error: src refspec story/2005184 does not match any. error: failed to push some refs to 'ssh://dominig@review.opendev.org:29418/starlingx/docs.git'
My changes are not rocket science (see diff bellow) but still did not make it :-( The pending review is not visible in Gerrit.
-- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
diff --git a/doc/source/developer_resources/navigate_source_code.rst b/doc/source/developer_resources/navigate_source_code.rst index 7a14dfe..3d597f6 100644 --- a/doc/source/developer_resources/navigate_source_code.rst +++ b/doc/source/developer_resources/navigate_source_code.rst @@ -2,9 +2,61 @@ How to navigate the StarlingX source code =========================================
-This topic is coming soon. +The StartlingX code is kept in various git directories. In order to simplify the downloading process of keeping your local copy up to date, StartlingX project provides Android type repo manifests which can be followed by the repo tool. + + +^^^^^^^^^^^^^^^^^ +Tools required +^^^^^^^^^^^^^^^^^ + + On top of your prefer text editor you will need two tools to download the StartlingX source code: + - git (certainly available from your prefered Linux distro) + - Android repo tool. A simple python script that is installed manually. + + To install git, follow the instruction to install git package from your Linux distro. + + To install the required Android Repo Tool in the Linux host system. Follow + the steps in the `Installing + Repo + <https://source.android.com/setup/build/downloading#installing-repo>` + + You will find more details on the repo tool `here + <https://source.android.com/setup/develop/repo>` + + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Initial download of StartlingX code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Create a *starlingx* workspace directory on your system. + Best practices dictate creating the workspace directory + in your $HOME directory: + + .. code:: sh + + $ mkdir -p $HOME/starlingx/ + +#. Use the repo tool to create a local clone of the manifest + Git repository based on the "master" branch: + + .. code:: sh + + $ cd $MY_REPO_ROOT_DIR + $ repo init -u https://opendev.org/starlingx/manifest -m + default.xml + +#. Synchronize the repository: + + .. code:: sh + + $ repo sync -j`nproc` + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Keeping in sync with StartlingX upstream code code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + .. code:: sh + + $ repo sync -j`nproc` +
-Linked Story does not yet exist.
.. `Linked Story <https://storyboard.openstack.org/#!/story/2005184>`__
~
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Geoffroy, not easy to shooting the dark. There is no space in my commit. git review -t "initial creation Doc page Navigate Git Code story/2005184" Dominig On 12/09/2019 17:20, VanCutsem, Geoffroy wrote:
A bit of a shot in the dark but I suspect it has to do with the spaces in the " initial creation Doc page Navigate Git Code story" string
-----Original Message----- From: Dominig ar Foll (Intel Open Source) <dominig.arfoll@fridu.net> Sent: Thursday, September 12, 2019 4:15 PM To: starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Full process to update/add documentation pages (gerrit review push issue)
On 12/09/2019 15:52, Jeremy Stanley wrote:
https://docs.openstack.org/infra/manual/developers.html
It covers topics such as Gerrit account setup.
Thanks that bit is helpful.
But my review still fails. dominig@dominig- t480:~/starlingx/git/docs/doc/source/developer_resources> git review -t "initial creation Doc page Navigate Git Code story/2005184" Creating a git remote called 'gerrit' that maps to: ssh://dominig@review.opendev.org:29418/starlingx/docs.git Your change was committed before the commit hook was installed. Amending the commit to add a gerrit change id. error: src refspec creation does not match any. error: src refspec Doc does not match any. error: src refspec page does not match any. error: src refspec Navigate does not match any. error: src refspec Git does not match any. error: src refspec Code does not match any. error: src refspec story/2005184 does not match any. error: failed to push some refs to 'ssh://dominig@review.opendev.org:29418/starlingx/docs.git'
My changes are not rocket science (see diff bellow) but still did not make it :-( The pending review is not visible in Gerrit.
-- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
diff --git a/doc/source/developer_resources/navigate_source_code.rst b/doc/source/developer_resources/navigate_source_code.rst index 7a14dfe..3d597f6 100644 --- a/doc/source/developer_resources/navigate_source_code.rst +++ b/doc/source/developer_resources/navigate_source_code.rst @@ -2,9 +2,61 @@ How to navigate the StarlingX source code =========================================
-This topic is coming soon. +The StartlingX code is kept in various git directories. In order to simplify the downloading process of keeping your local copy up to date, StartlingX project provides Android type repo manifests which can be followed by the repo tool. + + +^^^^^^^^^^^^^^^^^ +Tools required +^^^^^^^^^^^^^^^^^ + + On top of your prefer text editor you will need two tools to download the StartlingX source code: + - git (certainly available from your prefered Linux distro) + - Android repo tool. A simple python script that is installed manually. + + To install git, follow the instruction to install git package from your Linux distro. + + To install the required Android Repo Tool in the Linux host system. Follow + the steps in the `Installing + Repo + <https://source.android.com/setup/build/downloading#installing-repo>` + + You will find more details on the repo tool `here + <https://source.android.com/setup/develop/repo>` + + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Initial download of StartlingX code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Create a *starlingx* workspace directory on your system. + Best practices dictate creating the workspace directory + in your $HOME directory: + + .. code:: sh + + $ mkdir -p $HOME/starlingx/ + +#. Use the repo tool to create a local clone of the manifest + Git repository based on the "master" branch: + + .. code:: sh + + $ cd $MY_REPO_ROOT_DIR + $ repo init -u https://opendev.org/starlingx/manifest -m + default.xml + +#. Synchronize the repository: + + .. code:: sh + + $ repo sync -j`nproc` + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Keeping in sync with StartlingX upstream code code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + .. code:: sh + + $ repo sync -j`nproc` +
-Linked Story does not yet exist.
.. `Linked Story <https://storyboard.openstack.org/#!/story/2005184>`__
~
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
-- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
You have spaces in the topic string. What I meant was using something like this instead: git review -t create-doc-page-Navigate-Git-Code-story/2005184
-----Original Message----- From: Dominig ar Foll (Intel Open Source) <dominig.arfoll@fridu.net> Sent: Thursday, September 12, 2019 5:44 PM To: starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Full process to update/add documentation pages (gerrit review push issue)
Geoffroy,
not easy to shooting the dark. There is no space in my commit.
git review -t "initial creation Doc page Navigate Git Code story/2005184"
Dominig
On 12/09/2019 17:20, VanCutsem, Geoffroy wrote:
A bit of a shot in the dark but I suspect it has to do with the spaces in the " initial creation Doc page Navigate Git Code story" string
-----Original Message----- From: Dominig ar Foll (Intel Open Source) <dominig.arfoll@fridu.net> Sent: Thursday, September 12, 2019 4:15 PM To: starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Full process to update/add documentation pages (gerrit review push issue)
On 12/09/2019 15:52, Jeremy Stanley wrote:
https://docs.openstack.org/infra/manual/developers.html
It covers topics such as Gerrit account setup.
Thanks that bit is helpful.
But my review still fails. dominig@dominig- t480:~/starlingx/git/docs/doc/source/developer_resources> git review -t "initial creation Doc page Navigate Git Code story/2005184" Creating a git remote called 'gerrit' that maps to: ssh://dominig@review.opendev.org:29418/starlingx/docs.git Your change was committed before the commit hook was installed. Amending the commit to add a gerrit change id. error: src refspec creation does not match any. error: src refspec Doc does not match any. error: src refspec page does not match any. error: src refspec Navigate does not match any. error: src refspec Git does not match any. error: src refspec Code does not match any. error: src refspec story/2005184 does not match any. error: failed to push some refs to 'ssh://dominig@review.opendev.org:29418/starlingx/docs.git'
My changes are not rocket science (see diff bellow) but still did not make it :-( The pending review is not visible in Gerrit.
-- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
diff --git a/doc/source/developer_resources/navigate_source_code.rst b/doc/source/developer_resources/navigate_source_code.rst index 7a14dfe..3d597f6 100644 --- a/doc/source/developer_resources/navigate_source_code.rst +++ b/doc/source/developer_resources/navigate_source_code.rst @@ -2,9 +2,61 @@ How to navigate the StarlingX source code =========================================
-This topic is coming soon. +The StartlingX code is kept in various git directories. In order to +simplify the downloading process of keeping your local copy up to date, StartlingX project provides Android type repo manifests which can be followed by the repo tool. + + +^^^^^^^^^^^^^^^^^ +Tools required +^^^^^^^^^^^^^^^^^ + + On top of your prefer text editor you will need two tools to + download the StartlingX source code: + - git (certainly available from your prefered Linux distro) + - Android repo tool. A simple python script that is installed manually. + + To install git, follow the instruction to install git package + from your Linux distro. + + To install the required Android Repo Tool in the Linux host system. Follow + the steps in the `Installing + Repo + <https://source.android.com/setup/build/downloading#installing-repo + >` + + You will find more details on the repo tool `here + <https://source.android.com/setup/develop/repo>` + + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Initial download of StartlingX code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Create a *starlingx* workspace directory on your system. + Best practices dictate creating the workspace directory + in your $HOME directory: + + .. code:: sh + + $ mkdir -p $HOME/starlingx/ + +#. Use the repo tool to create a local clone of the manifest + Git repository based on the "master" branch: + + .. code:: sh + + $ cd $MY_REPO_ROOT_DIR + $ repo init -u https://opendev.org/starlingx/manifest -m + default.xml + +#. Synchronize the repository: + + .. code:: sh + + $ repo sync -j`nproc` + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Keeping in sync with StartlingX upstream code code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + .. code:: sh + + $ repo sync -j`nproc` +
-Linked Story does not yet exist.
.. `Linked Story <https://storyboard.openstack.org/#!/story/2005184>`__
~
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
-- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Hi Dominig, Which steps have you performed before trying to upload your commit to Gerrit? Have you initialized your local repo with ‘git review -s’ for instance after cloning it? I’m also a little confused by the command in your mail: git review -t "initial creation Doc page Navigate Git Code story/2005184” ‘-t’ specifies the Gerrit topic which should be not more than for instance 'story/2005184’. It looks like you are trying to add the commit message title to the topic which is a bit too long as topic text. If you are on IRC (#starlingx channel on Freenode) I can help figuring this out in a more synchronous way. Thanks, Ildikó
On 2019. Sep 12., at 17:53, VanCutsem, Geoffroy <geoffroy.vancutsem@intel.com> wrote:
You have spaces in the topic string. What I meant was using something like this instead:
git review -t create-doc-page-Navigate-Git-Code-story/2005184
-----Original Message----- From: Dominig ar Foll (Intel Open Source) <dominig.arfoll@fridu.net> Sent: Thursday, September 12, 2019 5:44 PM To: starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Full process to update/add documentation pages (gerrit review push issue)
Geoffroy,
not easy to shooting the dark. There is no space in my commit.
git review -t "initial creation Doc page Navigate Git Code story/2005184"
Dominig
On 12/09/2019 17:20, VanCutsem, Geoffroy wrote:
A bit of a shot in the dark but I suspect it has to do with the spaces in the " initial creation Doc page Navigate Git Code story" string
-----Original Message----- From: Dominig ar Foll (Intel Open Source) <dominig.arfoll@fridu.net> Sent: Thursday, September 12, 2019 4:15 PM To: starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Full process to update/add documentation pages (gerrit review push issue)
On 12/09/2019 15:52, Jeremy Stanley wrote:
https://docs.openstack.org/infra/manual/developers.html
It covers topics such as Gerrit account setup. Thanks that bit is helpful.
But my review still fails. dominig@dominig- t480:~/starlingx/git/docs/doc/source/developer_resources> git review -t "initial creation Doc page Navigate Git Code story/2005184" Creating a git remote called 'gerrit' that maps to: ssh://dominig@review.opendev.org:29418/starlingx/docs.git Your change was committed before the commit hook was installed. Amending the commit to add a gerrit change id. error: src refspec creation does not match any. error: src refspec Doc does not match any. error: src refspec page does not match any. error: src refspec Navigate does not match any. error: src refspec Git does not match any. error: src refspec Code does not match any. error: src refspec story/2005184 does not match any. error: failed to push some refs to 'ssh://dominig@review.opendev.org:29418/starlingx/docs.git'
My changes are not rocket science (see diff bellow) but still did not make it :-( The pending review is not visible in Gerrit.
-- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
diff --git a/doc/source/developer_resources/navigate_source_code.rst b/doc/source/developer_resources/navigate_source_code.rst index 7a14dfe..3d597f6 100644 --- a/doc/source/developer_resources/navigate_source_code.rst +++ b/doc/source/developer_resources/navigate_source_code.rst @@ -2,9 +2,61 @@ How to navigate the StarlingX source code =========================================
-This topic is coming soon. +The StartlingX code is kept in various git directories. In order to +simplify the downloading process of keeping your local copy up to date, StartlingX project provides Android type repo manifests which can be followed by the repo tool. + + +^^^^^^^^^^^^^^^^^ +Tools required +^^^^^^^^^^^^^^^^^ + + On top of your prefer text editor you will need two tools to + download the StartlingX source code: + - git (certainly available from your prefered Linux distro) + - Android repo tool. A simple python script that is installed manually. + + To install git, follow the instruction to install git package + from your Linux distro. + + To install the required Android Repo Tool in the Linux host system. Follow + the steps in the `Installing + Repo + <https://source.android.com/setup/build/downloading#installing-repo + >` + + You will find more details on the repo tool `here + <https://source.android.com/setup/develop/repo>` + + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Initial download of StartlingX code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Create a *starlingx* workspace directory on your system. + Best practices dictate creating the workspace directory + in your $HOME directory: + + .. code:: sh + + $ mkdir -p $HOME/starlingx/ + +#. Use the repo tool to create a local clone of the manifest + Git repository based on the "master" branch: + + .. code:: sh + + $ cd $MY_REPO_ROOT_DIR + $ repo init -u https://opendev.org/starlingx/manifest -m + default.xml + +#. Synchronize the repository: + + .. code:: sh + + $ repo sync -j`nproc` + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Keeping in sync with StartlingX upstream code code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + .. code:: sh + + $ repo sync -j`nproc` +
-Linked Story does not yet exist.
.. `Linked Story <https://storyboard.openstack.org/#!/story/2005184>`__
~
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
-- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
On 12/09/2019 18:41, Ildiko Vancsa wrote:
Hi Dominig,
Which steps have you performed before trying to upload your commit to Gerrit?
Have you initialized your local repo with ‘git review -s’ for instance after cloning it?
I’m also a little confused by the command in your mail: git review -t "initial creation Doc page Navigate Git Code story/2005184”
‘-t’ specifies the Gerrit topic which should be not more than for instance 'story/2005184’. It looks like you are trying to add the commit message title to the topic which is a bit too long as topic text.
If you are on IRC (#starlingx channel on Freenode) I can help figuring this out in a more synchronous way. OK, it seems that Geoffroy as usual had a great idea to work around the issue. Geoffroy thanks your trick of removing spaces, worked.
When it come to the user of -t, I guessed from the git-review that adding a topic would be helpful, but without guidance on documentation, I did like what I was doing in AGL. So I did clone the documentation repo git clone https://opendev.org/starlingx/docs git clone https://opendev.org/starlingx/specs # added my page with my prefered text editor # then git commit -sam "initial creation Doc page Navigate Git Code story/2005184" git review -t "initial creation Doc page Navigate Git Code story/2005184" # !!oups that did not work. I got a not that helpful error message git review -t "initial_creation_Doc_page_Navigate_Git_Code_story/2005184" # that one was accepted with a warning on the length of my topic. If someone knows what should actually be done, it would be nice to add it to the documentation on how to improve documentation. https://docs.starlingx.io/contributor/doc_contribute_guide.html So far the only guidance is : ... and then submit the changes to Gerrit for approval. ... -- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
My workflow is different. # git commit -s <edit commit message, add story number, etc...> # git review The tools want a specific format in the commit message, which is easier for me to get right this way. brucej -----Original Message----- From: Dominig ar Foll (Intel Open Source) [mailto:dominig.arfoll@fridu.net] Sent: Thursday, September 12, 2019 10:43 AM To: Ildiko Vancsa <ildiko.vancsa@gmail.com> Cc: starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Full process to update/add documentation pages (gerrit review push issue) On 12/09/2019 18:41, Ildiko Vancsa wrote:
Hi Dominig,
Which steps have you performed before trying to upload your commit to Gerrit?
Have you initialized your local repo with ‘git review -s’ for instance after cloning it?
I’m also a little confused by the command in your mail: git review -t "initial creation Doc page Navigate Git Code story/2005184”
‘-t’ specifies the Gerrit topic which should be not more than for instance 'story/2005184’. It looks like you are trying to add the commit message title to the topic which is a bit too long as topic text.
If you are on IRC (#starlingx channel on Freenode) I can help figuring this out in a more synchronous way. OK, it seems that Geoffroy as usual had a great idea to work around the issue. Geoffroy thanks your trick of removing spaces, worked.
When it come to the user of -t, I guessed from the git-review that adding a topic would be helpful, but without guidance on documentation, I did like what I was doing in AGL. So I did clone the documentation repo git clone https://opendev.org/starlingx/docs git clone https://opendev.org/starlingx/specs # added my page with my prefered text editor # then git commit -sam "initial creation Doc page Navigate Git Code story/2005184" git review -t "initial creation Doc page Navigate Git Code story/2005184" # !!oups that did not work. I got a not that helpful error message git review -t "initial_creation_Doc_page_Navigate_Git_Code_story/2005184" # that one was accepted with a warning on the length of my topic. If someone knows what should actually be done, it would be nice to add it to the documentation on how to improve documentation. https://docs.starlingx.io/contributor/doc_contribute_guide.html So far the only guidance is : ... and then submit the changes to Gerrit for approval. ... -- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
My workflow is different.
# git commit -s <edit commit message, add story number, etc...> # git review
The tools want a specific format in the commit message, which is easier for me to get right this way.
This is my typical development workflow, using http instead of ssh, Ubuntu account already setup: user@workstation:~$ git clone https://opendev.org/starlingx/docs.git user@workstation:~$ cd docs/ user@workstation:~/docs$ git remote add gerrit https://abraham@review.opendev.org/starlingx/docs.git user@workstation:~/docs$ git review -s user@workstation:~/docs$ git remote -v user@workstation:~/docs$ git remote update user@workstation:~/docs$ git checkout master user@workstation:~/docs$ git pull --ff-only origin master user@workstation:~/docs$ git checkout -b abraham-test user@workstation:~/docs$ git add .. user@workstation:~/docs$ git commit -s user@workstation:~/docs$ git review Best Regards Abraham
Hi Dominig, There are some plans to make some of the documentation that is currently written up in the OpenStack Contributor Guide to be made available to all OSF projects using OpenDev tooling. In the meantime please refer to this page for some Git/Gerrit best practices: https://docs.openstack.org/contributors/code-and-documentation/patch-best-pr... I don’t think we have strong guidelines when it comes to Gerrit topics. A rule of thumb is to keep it short and informative, people often refer to Launchpad or Storyboard identifiers, like 'bug/<bug_id>’ or ’story/<story_id>’. It really only matters if there are multiple changes that are related but not organized in a chain of patches so you can use the Gerrit topic as a search filter to display all the relevant changes at once. I hope this helps. Please let me know if you have further questions. Thanks, Ildikó
On 2019. Sep 12., at 19:43, Dominig ar Foll (Intel Open Source) <dominig.arfoll@fridu.net> wrote:
On 12/09/2019 18:41, Ildiko Vancsa wrote:
Hi Dominig,
Which steps have you performed before trying to upload your commit to Gerrit?
Have you initialized your local repo with ‘git review -s’ for instance after cloning it?
I’m also a little confused by the command in your mail: git review -t "initial creation Doc page Navigate Git Code story/2005184”
‘-t’ specifies the Gerrit topic which should be not more than for instance 'story/2005184’. It looks like you are trying to add the commit message title to the topic which is a bit too long as topic text.
If you are on IRC (#starlingx channel on Freenode) I can help figuring this out in a more synchronous way. OK, it seems that Geoffroy as usual had a great idea to work around the issue. Geoffroy thanks your trick of removing spaces, worked.
When it come to the user of -t, I guessed from the git-review that adding a topic would be helpful, but without guidance on documentation, I did like what I was doing in AGL.
So I did clone the documentation repo git clone https://opendev.org/starlingx/docs git clone https://opendev.org/starlingx/specs
# added my page with my prefered text editor # then git commit -sam "initial creation Doc page Navigate Git Code story/2005184" git review -t "initial creation Doc page Navigate Git Code story/2005184" # !!oups that did not work. I got a not that helpful error message git review -t "initial_creation_Doc_page_Navigate_Git_Code_story/2005184" # that one was accepted with a warning on the length of my topic.
If someone knows what should actually be done, it would be nice to add it to the documentation on how to improve documentation. https://docs.starlingx.io/contributor/doc_contribute_guide.html So far the only guidance is : ... and then submit the changes to Gerrit for approval. ...
-- Dominig ar Foll Senior Software Architect Intel Open Source Technology Centre
On 2019-09-12 16:15:16 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote: [...]
git review -t "initial creation Doc page Navigate Git Code story/2005184" [...] error: src refspec creation does not match any. error: src refspec Doc does not match any. error: src refspec page does not match any. error: src refspec Navigate does not match any. error: src refspec Git does not match any. error: src refspec Code does not match any. error: src refspec story/2005184 does not match any. [...]
I know it's been worked around and discussed in other replies already, but just to follow up I'm trying to work out whether spaces in change topics should be supported. I'd never tried it before, and indeed all the documentation (including Gerrit's own) has no examples of setting a topic with a space in it via git push (what git review is using behind the scenes there). Gerrit *does* let you set change topics with spaces in them through its WebUI, but I can't figure out any viable quoting or encoding solution to create them on push. At best, we should probably trap for such attempts in the git-review option parser and return a sensible error message, so thanks for bringing this to light. I'll get some solution for this into the next release so it hopefully doesn't bite anyone else. -- Jeremy Stanley
On Thu, 2019-09-12 at 23:14 +0000, Jeremy Stanley wrote:
On 2019-09-12 16:15:16 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote: [...]
git review -t "initial creation Doc page Navigate Git Code story/2005184" [...] error: src refspec creation does not match any. error: src refspec Doc does not match any. error: src refspec page does not match any. error: src refspec Navigate does not match any. error: src refspec Git does not match any. error: src refspec Code does not match any. error: src refspec story/2005184 does not match any. [...]
I know it's been worked around and discussed in other replies already, but just to follow up I'm trying to work out whether spaces in change topics should be supported. I'd never tried it before, and indeed all the documentation (including Gerrit's own) has no examples of setting a topic with a space in it via git push (what git review is using behind the scenes there). Gerrit *does* let you set change topics with spaces in them through its WebUI, but I can't figure out any viable quoting or encoding solution to create them on push. At best, we should probably trap for such attempts in the git-review option parser and return a sensible error message, so thanks for bringing this to light. I'll get some solution for this into the next release so it hopefully doesn't bite anyone else.
I suspect this is a problem at the git-review Python code, not a problem with Gerrit itself. I took a (very) quick look at the code and noticed it uses the 'argparse' module to parse all arguments. This is the issue I believe we're hitting: https://bugs.python.org/issue22433 ... unfortunately it's been sitting there, opened for 5 years now. Note: enclosing the string in quotes should help but I've seen reports that it would only work when using '--topic='. @Dominig, if you can spare a couple of minutes, I'd be curious to know if the following command works for you: git review --topic="initial creation Doc page Navigate Git Code story/2005184" Geoffroy
On 2019-09-13 10:53:16 +0000 (+0000), VanCutsem, Geoffroy wrote: [...]
I suspect this is a problem at the git-review Python code, not a problem with Gerrit itself. I took a (very) quick look at the code and noticed it uses the 'argparse' module to parse all arguments. This is the issue I believe we're hitting: https://bugs.python.org/issue22433 ... unfortunately it's been sitting there, opened for 5 years now.
Note: enclosing the string in quotes should help but I've seen reports that it would only work when using '--topic='.
@Dominig, if you can spare a couple of minutes, I'd be curious to know if the following command works for you: git review --topic="initial creation Doc page Navigate Git Code story/2005184"
It's a good guess, but no I tried all manner of passing the option and also more robust sorts of quoting directly in the parameter handling routines in git-review's source code. Where I'm stuck is that the serialization Gerrit uses for "push options" to communicate a change topic during a git push operation seems to have no means of encoding spaces. These do not work to set a topic of "topic spaces": git push gerrit HEAD:refs/for/master%topic=topic spaces git push gerrit HEAD:refs/for/master%topic='topic spaces' git push gerrit HEAD:refs/for/master%topic="topic spaces" git push gerrit HEAD:refs/for/master%"topic=topic spaces" git push gerrit HEAD:"refs/for/master%topic=topic spaces" git push gerrit "HEAD:refs/for/master%topic=topic spaces" ...and so on. As best I can tell, Git refspecs simply cannot contain spaces. There is a converse problem as well, that git review -d to retrieve a change from Gerrit wants to create a local branch incorporating the change topic string, and Git doesn't allow spaces in branch names either. So I think we're going to just need to have git-review check for spaces when pushing and either transliterate or reject them, but also have it check for them when downloading changes and perform substitutions in that direction as well. -- Jeremy Stanley
On Fri, 2019-09-13 at 13:55 +0000, Jeremy Stanley wrote:
On 2019-09-13 10:53:16 +0000 (+0000), VanCutsem, Geoffroy wrote: [...]
I suspect this is a problem at the git-review Python code, not a problem with Gerrit itself. I took a (very) quick look at the code and noticed it uses the 'argparse' module to parse all arguments. This is the issue I believe we're hitting: https://bugs.python.org/issue22433 ... unfortunately it's been sitting there, opened for 5 years now.
Note: enclosing the string in quotes should help but I've seen reports that it would only work when using '--topic='.
@Dominig, if you can spare a couple of minutes, I'd be curious to know if the following command works for you: git review --topic="initial creation Doc page Navigate Git Code story/2005184"
It's a good guess, but no I tried all manner of passing the option and also more robust sorts of quoting directly in the parameter handling routines in git-review's source code. Where I'm stuck is that the serialization Gerrit uses for "push options" to communicate a change topic during a git push operation seems to have no means of encoding spaces. These do not work to set a topic of "topic spaces":
git push gerrit HEAD:refs/for/master%topic=topic spaces
git push gerrit HEAD:refs/for/master%topic='topic spaces'
git push gerrit HEAD:refs/for/master%topic="topic spaces"
git push gerrit HEAD:refs/for/master%"topic=topic spaces"
git push gerrit HEAD:"refs/for/master%topic=topic spaces"
git push gerrit "HEAD:refs/for/master%topic=topic spaces"
...and so on. As best I can tell, Git refspecs simply cannot contain spaces. There is a converse problem as well, that git review -d to retrieve a change from Gerrit wants to create a local branch incorporating the change topic string, and Git doesn't allow spaces in branch names either. So I think we're going to just need to have git-review check for spaces when pushing and either transliterate or reject them, but also have it check for them when downloading changes and perform substitutions in that direction as well.
Makes sense to me. Thanks for the additional investigation. Geoffroy
participants (6)
-
Arce Moreno, Abraham
-
Dominig ar Foll (Intel Open Source)
-
Ildiko Vancsa
-
Jeremy Stanley
-
Jones, Bruce E
-
VanCutsem, Geoffroy