Skip to content

Commit

Permalink
Merge pull request #29315 from jfindlay/docs
Browse files Browse the repository at this point in the history 
dev tutorial doc: fix markup errors
  • Loading branch information
@jfindlay
jfindlay committed Dec 1, 2015
2 parents a3a463f + e8e23dc commit 08ced73
Showing 1 changed file with 78 additions and 65 deletions.
143 changes: 78 additions & 65 deletions doc/topics/development/tutorial.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,26 @@ Developing Salt Tutorial
========================

This tutorial assumes you have:
- a web browser
- a GitHub account (``<my_account>``)
- a command line (CLI)
- git
- a text editor
* a web browser
* a GitHub account (``<my_account>``)
* a command line (CLI)
* git
* a text editor

----
Fork
----

In your browser, navigate to the ``saltstack/salt`` `GitHub repository
https://github.com/saltstack/salt`_.
<https://github.com/saltstack/salt>`_.

Click on ``Fork`` (https://github.com/saltstack/salt/#fork-destination-box).

.. note::

If you have more than one GitHub presence, for example if you are a member of
a team, GitHub will ask you into which area to clone Salt. If you don't know
where, then select your personal GitHub account.
If you have more than one GitHub presence, for example if you are a member
of a team, GitHub will ask you into which area to clone Salt. If you don't
know where, then select your personal GitHub account.

-----
Clone
Expand All @@ -33,17 +33,17 @@ codebase and submit the following command:

.. code-block:: shell
$ git clone https://github.com/<my_account>/salt.git
$ git clone https://github.com/<my_account>/salt.git
where ``<my_account>`` is the name of your GitHub account. After the clone has
completed, add SaltStack as a second remote and fetch any changes from
``upstream``.

.. code-block:: shell
$ cd salt
$ git remote add upstream https://github.com/saltstack/salt.git
$ git fetch upstream
$ cd salt
$ git remote add upstream https://github.com/saltstack/salt.git
$ git fetch upstream
For this tutorial, we will be working off from the ``develop`` branch, which is
the default branch for the SaltStack GitHub project. This branch needs to
Expand All @@ -52,8 +52,8 @@ happen.

.. code-block:: shell
$ git checkout develop
$ git branch --set-upstream-to upstream/develop
$ git checkout develop
$ git branch --set-upstream-to upstream/develop
-----
Fetch
Expand All @@ -64,28 +64,29 @@ local copy of the branch with a single command:

.. code-block:: shell
$ git pull --rebase
$ git pull --rebase
.. note::

For an explanation on ``pull`` vs ``pull --rebase`` and other excellent
points, see `this article http://mislav.net/2013/02/merge-vs-rebase/`_ by
Mislav Marohnić.
For an explanation on ``pull`` vs ``pull --rebase`` and other excellent
points, see `this article <http://mislav.net/2013/02/merge-vs-rebase/>`_ by
Mislav Marohnić.

------
Branch
------

Now we are ready to get to work. Consult the sprint beginner bug list and
select an execution module whose ``__virtual__`` function needs to be updated.
I'll select the ``alternatives`` module.
Now we are ready to get to work. Consult the `sprint beginner bug list
<https://github.com/saltstack/salt/wiki/December-2015-Sprint-Beginner-Bug-List>`_
and select an execution module whose ``__virtual__`` function needs to be
updated. I'll select the ``alternatives`` module.

Create a new branch off from ``develop``. Be sure to name it something short
and descriptive.

.. code-block:: shell
$ git checkout -b virt_ret
$ git checkout -b virt_ret
----
Edit
Expand All @@ -95,21 +96,21 @@ Edit the file you have selected, and verify that the changes are correct.

.. code-block:: shell
$ vim salt/modules/alternatives.py
$ git diff
diff --git a/salt/modules/alternatives.py b/salt/modules/alternatives.py
index 1653e5f..30c0a59 100644
--- a/salt/modules/alternatives.py
+++ b/salt/modules/alternatives.py
@@ -30,7 +30,7 @@ def __virtual__():
'''
if os.path.isdir('/etc/alternatives'):
return True
- return False
+ return (False, 'Cannot load alternatives module: /etc/alternatives dir not found')
$ vim salt/modules/alternatives.py
$ git diff
diff --git a/salt/modules/alternatives.py b/salt/modules/alternatives.py
index 1653e5f..30c0a59 100644
--- a/salt/modules/alternatives.py
+++ b/salt/modules/alternatives.py
@@ -30,7 +30,7 @@ def __virtual__():
'''
if os.path.isdir('/etc/alternatives'):
return True
- return False
+ return (False, 'Cannot load alternatives module: /etc/alternatives dir not found')
def _get_cmd():
def _get_cmd():
------
Commit
Expand All @@ -120,17 +121,17 @@ keep it less than 50 characters. Review your commit.
.. code-block:: shell
$ git add salt/modules/alternatives.py
$ git commit -m 'alternatives module: add error msg to __virtual__ return'
$ git show
$ git add salt/modules/alternatives.py
$ git commit -m 'modules.alternatives: __virtual__ return err msg'
$ git show
.. note::
If you need more room to describe the changes in your commit, run ``git
commit`` (without the ``-m``, message, option) and you will be presented with
an editor. The first line is the commit summary and should still be 50
characters or less. The following paragraphs you create are free form and
will be preserved as part of the commit.
If you need more room to describe the changes in your commit, run ``git
commit`` (without the ``-m``, message, option) and you will be presented
with an editor. The first line is the commit summary and should still be
50 characters or less. The following paragraphs you create are free form
and will be preserved as part of the commit.
----
Push
Expand All @@ -141,46 +142,53 @@ GitHub username and password.
.. code-block:: shell
$ git push origin virt_ret
Username for 'https://github.com': <my_account>
Password for 'https://<my_account>@github.com':
$ git push origin virt_ret
Username for 'https://github.com': <my_account>
Password for 'https://<my_account>@github.com':
.. note::
If authentication over https does not work, you can alternatively setup `ssh
keys https://help.github.com/articles/generating-ssh-keys/`_. Once you have
done this, you may need add the keys to your git repository configuration
If authentication over https does not work, you can alternatively setup
`ssh keys <https://help.github.com/articles/generating-ssh-keys/>`_. Once
you have done this, you may need add the keys to your git repository
configuration
.. code-block:: shell
.. code-block:: shell
$ git config ssh.key ~/.ssh/<key_name>
$ git config ssh.key ~/.ssh/<key_name>
where ``<key_name>`` is the file name of the private key you created.
where ``<key_name>`` is the file name of the private key you created.
-----
Merge
-----
In your browser, navigate to the `new pull request
https://github.com/saltstack/salt/compare`_ page on the ``saltstack/salt``
GitHub repository and click on 'compare across forks'. Select ``<my_account>``
from the list of head forks and the branch you are wanting to merge into
``develop`` (``virt_ret`` in this case).
<https://github.com/saltstack/salt/compare>`_ page on the ``saltstack/salt``
GitHub repository and click on ``compare across forks``. Select
``<my_account>`` from the list of head forks and the branch you are wanting to
merge into ``develop`` (``virt_ret`` in this case).
When you have finished reviewing the changes, click 'Create pull request'.
When you have finished reviewing the changes, click ``Create pull request``.
If your pull request contains only a single commit, the title and comment will
be taken from that commit's summary and message, otherwise the branch name is
used for the title. Edit these fields as necessary and click ``Create pull
request``.

.. note::

Although these instructions seem to be the official pull request proceedure
on github's website, here are two alternative methods that are simpler.
Although these instructions seem to be the official pull request proceedure
on github's website, here are two alternative methods that are simpler.

If you navigate to your clone of salt, https://github.com/<my_account>/salt,
depending on how old your branch is or how recently you pushed updates on it,
you may be presented with a button to create a pull request with your branch.
* If you navigate to your clone of salt,
``https://github.com/<my_account>/salt``, depending on how old your
branch is or how recently you pushed updates on it, you may be presented
with a button to create a pull request with your branch.

I find it easiest to edit the following URL:
* I find it easiest to edit the following URL:

``https://github.com/saltstack/salt/compare/develop...<my_account>:virt_ret``
``https://github.com/saltstack/salt/compare/develop...<my_account>:virt_ret``

---------
Resources
Expand All @@ -194,3 +202,8 @@ https://help.github.com/
There are many topics covered by the Salt Developer documentation:

https://docs.saltstack.com/en/latest/topics/development/index.html

The contributing documentation presents more details on specific contributing
topics:

https://docs.saltstack.com/en/latest/topics/development/contributing.html

0 comments on commit 08ced73

Please sign in to comment.