opendev
/
infra-manual
Code Issues Proposed changes

Update the sandbox instructions 

Clarify the instructions, reduce ambiguity, increase consistency.
Rather than change the legacy OpenStack  URLs, I changed the text to
acknowledge that we refer to OpenStack.

Change-Id: Ic1a377d3572bb110613357caa2272d8f8ba6ac56
This commit is contained in:
Blaise Pabon 2022-06-13 09:50:40 -04:00 committed by Blaise R Pabon
parent 6e166e7581
commit b5b046ea46
1 changed files with 57 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
doc/source/sandbox.rst
View File

@ -21,17 +21,30 @@ Move into the root directory for the sandbox repo::
Configure Git::
git config user.name "firstname lastname"
git config user.email "yourname@yourdomain.tld"
git config core.editor "yourfavouriteeditor"
git config user.name "first_name last_name"
git config user.email "your_name@your_domain.tld"
git config core.editor "your_favourite_editor"
Then configure git-review so that it knows about Gerrit. If you don't, it will
do so the first time you submit a change for review. You will probably want to
do this ahead of time though so the Gerrit Change-Id commit hook gets
(Inside the quotes, replace those placeholders with your details.)
The email should match one of the emails you listed in your
Gerrit account. Then configure git-review so that it knows about Gerrit. If you don't, it will
do so the first time you submit a change for review.
Prepare ``git-review`` for Gerrit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many IDE's support Gerrit and you can use them natively with OpenDev.
This document will describe the Gerrit command line interface, ``git-review``. Gerrit needs to know a few things about you and your repo before it will enable you to push changes.
You will probably want to do this ahead of time, so the Gerrit ``Change-Id`` commit hook gets
installed. To do so::
git review -s
and then ``git-review`` will prompt you for details about your OpenDev Gerrit settings.
Checkout a new branch
~~~~~~~~~~~~~~~~~~~~~
Create a git branch locally from the sandbox repo master branch::
git checkout -b new-branch
@ -39,37 +52,53 @@ Create a git branch locally from the sandbox repo master branch::
Create a new file, add some content and save the file::
cat > first-file << EOF
This is my first changeset for OpenStack.
This is my first changeset for the sandbox.
EOF
Run::
git status
Three ways to stage changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are three ways you can stage your changes.
Stage a single file
```````````````````
You can explicitly stage your new file with::
git add first-file
or, you can stage all new and modified files with::
Stage only modified and new files
`````````````````````````````````
you can stage all new and modified files with::
git add .
Stage all files
```````````````
or, you can stage ALL files (including deleted files) with::
git add -A
How to commit your change
~~~~~~~~~~~~~~~~~~~~~~~~~
Next commit your change with::
git commit
.. note::
This will take you into your editor which you set with ``git config core.editor``.
``git`` will open the commit description in the editor which you set earlier using ``git config core.editor``.
`Create a title for your commit message and add some text in the body.
<https://wiki.openstack.org/wiki/GitCommitMessages#Summary_of_Git_commit_message_structure>`_
Then save the file and close the editor. Next submit your patchset to gerrit::
Create a title for your commit message and add some text in the body. OpenDev follows `these guidelines for commit messages
<https://wiki.openstack.org/wiki/GitCommitMessages#Summary_of_Git_commit_message_structure>`_.
Then save the file and close the editor.
Now you can submit your patchset to Gerrit::
git review
@ -77,16 +106,19 @@ You will see on screen a message confirming that the change has been
submitted for review and a URL to your change on
https://review.opendev.org. Click on the URL and view your patchset.
You will also receive one or more emails from the
`automatic testing system <https://docs.openstack.org/infra/manual/developers.html#automated-testing>`_,
You will also receive one or more emails from the :ref:`automated-testing`,
reporting the testing results of your newly committed change.
Create another patchset
```````````````````````
Now create a second patchset, in the same git branch as your first patchset.
Make some changes, add or delete content to the first-file or create a
new file::
cat > second-file << EOF
This is my second OpenStack file for that first changeset.
This is my second OpenDev file for that first changeset.
EOF
Now add the second file, as described previously, with::
@ -101,6 +133,9 @@ or::
git add -A
Include the new patchset in the same change
```````````````````````````````````````````
To ensure you submit your new patchset to the same change execute::
git commit -a --amend
@ -118,9 +153,14 @@ patchset 1. If you have two different URI something went wrong, most
likely you have not used ``--amend`` in your git commit or you've
changed the line Change-Id in your commit message.
Finally, abandon your change
````````````````````````````
As a last step, you should abandon your change. You can do this from
the web UI by visiting the URL of the change and hitting the *Abandon*
button. Alternatively you can abandon a change from command
button.
If you prefer the terminal, you can abandon a change from command
line using `Gerrit ssh commands <https://review.opendev.org/Documentation/cmd-review.html>`_::
ssh -l <YOUR_GERRIT_USERNAME>\
@ -128,3 +168,4 @@ line using `Gerrit ssh commands <https://review.opendev.org/Documentation/cmd-re
review.opendev.org 'gerrit review' \
--project opendev/sandbox.git \
--abandon <THE_CHANGE_ID>,2