valitydev/salt
14
0
Fork 0
mirror of https://github.com/valitydev/salt.git synced 2024-11-08 01:18:58 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #14384 from whiteinge/doc-merge-forward

Browse Source 
Updated the contributor documentation with the new branching workflow
This commit is contained in:
Joseph Hall 2014-07-22 09:14:54 -06:00
commit 3ec7361771
1 changed files with 171 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

262
doc/topics/development/contributing.rst
View File

@ -1,3 +1,4 @@
============
Contributing Contributing
============ ============
@ -5,67 +6,78 @@ There is a great need for contributions to Salt and patches are welcome! The goa
here is to make contributions clear, make sure there is a trail for where the code here is to make contributions clear, make sure there is a trail for where the code
has come from, and most importantly, to give credit where credit is due! has come from, and most importantly, to give credit where credit is due!
There are a number of ways to contribute to salt development. There are a number of ways to contribute to Salt development.
Sending a GitHub pull request
-----------------------------
This is the preferred method for contributions. Simply create a GitHub
fork, commit changes to the fork, and then open up a pull request.
The following is an example (from `Open Comparison Contributing Docs`_ )
of an efficient workflow for forking, cloning, branching, committing, and
sending a pull request for a GitHub repository.
First, make a local clone of your GitHub fork of the salt GitHub repo and make
edits and changes locally.
Then, create a new branch on your clone by entering the following commands:
.. code-block:: bash
git checkout -b fixed-broken-thing
Switched to a new branch 'fixed-broken-thing'
Choose a name for your branch that describes its purpose.
Now commit your changes to this new branch with the following command:
.. code-block:: bash
git commit -am 'description of my fixes for the broken thing'
.. note::
Using ``git commit -am``, followed by a quoted string, both stages and
commits all modified files in a single command. Depending on the nature of
your changes, you may wish to stage and commit them separately. Also, note
that if you wish to add newly-tracked files as part of your commit, they
will not be caught using ``git commit -am`` and will need to be added using
``git add`` before committing.
Push your locally-committed changes back up to GitHub:
.. code-block:: bash
git push --set-upstream origin fixed-broken-thing
Now go look at your fork of the salt repo on the GitHub website. The new
branch will now be listed under the "Source" tab where it says "Switch Branches".
Select the new branch from this list, and then click the "Pull request" button.
Put in a descriptive comment, and include links to any project issues related
to the pull request.
The repo managers will be notified of your pull request and it will be
reviewed. If a reviewer asks for changes, just make the changes locally in the
same local feature branch, push them to GitHub, then add a comment to the
discussion section of the pull request.
For details on how to contribute documentation improvements please review For details on how to contribute documentation improvements please review
:ref:`Writing Salt Documentation <salt-docs>`. :ref:`Writing Salt Documentation <salt-docs>`.
Sending a GitHub pull request
=============================
Sending pull requests on GitHub is the preferred method for receiving
contributions. The workflow advice below mirrors `GitHub's own guide <GitHub
Fork a Repo Guide>`_ and is well worth reading.
#. Fork the `saltstack/salt`_ repository on GitHub.
#. Make a local clone of your fork.
#. Create a new branch in your clone.
A branch should have one purpose. For example, "Fix bug X," or "Add feature
Y." Multiple pull requests should be opened for unrelated changes.
Choose a name for your branch that describes its purpose.
.. code-block:: bash
git checkout -b fixed-broken-thing
#. Make edits and changes locally.
#. Commit changes to this new branch.
Edit the necessary files in your Salt clone and remember to add them to
your commit. Write a descriptive commit message.
.. code-block:: bash
git add path/to/file1
git add path/to/file2
git commit -m "Fixed X in file1 and file2"
If you get stuck `there are many introductory Git resources on
help.github.com <Git resources>`_.
#. Push your locally-committed changes to your GitHub fork.
.. code-block:: bash
git push --set-upstream origin fixed-broken-thing
#. Go to your fork on the GitHub website & find your branch.
GitHub automatically displays a button with the text "Compare & pull
request" for recently pushed branches.
Otherwise click on the "Branches" tab at the top of your fork. A button
with the text "New pull request" will be beside each branch.
#. Open a new pull request.
#. Click one of the pull request buttons from the previous step. GitHub
will present a form and show a comparison of the changes in your pull
request.
#. Write a descriptive comment, include links to any project issues
related to the pull request.
#. Click "Create pull request".
#. The Salt repo managers will be notified of your pull request.
If a reviewer asks for changes:
#. Make the changes in your local clone on the same local branch.
#. Push the branch to GitHub using the same command as before.
#. The new commits will be reflected in the pull request automatically.
#. Feel free to add a comment to the discussion.
.. note:: Jenkins .. note:: Jenkins
Whenever you make a pull request against the main Salt repository your Whenever you make a pull request against the main Salt repository your
@ -79,65 +91,133 @@ For details on how to contribute documentation improvements please review
failure does not necessarily mean there is an issue in the associated pull failure does not necessarily mean there is an issue in the associated pull
request as the entire development branch is tested. request as the entire development branch is tested.
.. note:: Minor releases Which Salt branch?
==================
Minor releases normally contain bug fixes selected by the Salt core GitHub will open pull requests against Salt's main branch named ``develop`` by
development team. default. Most contributors can keep the default options. This section is for
advanced contributors.
When submitting a pull-request which should be considered for a minor Each pull request should address a single concern, as mentioned in the section
release, please note in the comments that it should be reviewed above. For example, "Fix bug X," or "Add feature Y." And a pull request should
for inclusion. be opened against the branch that corresponds to that concern.
Pull requests that are accepted to Salt but not merged into a minor The current release branch
release will always be available in the next major release.
Keeping Salt Forks in Sync
-------------------------- --------------------------
The current release branch is the most recent stable release. Pull requests
containing bug fixes should be made against the release branch.
The branch name will be a date-based name such as ``2014.7``.
Bug fixes are made on this branch so that minor releases can be cut from this
branch without introducing surprises and new features. This approach maximizes
stability.
The Salt development team will "merge-forward" any fixes made on the release
branch to the ``develop`` branch once the pull request has been accepted. This
keeps the fix in isolation on the release branch and also keeps the ``develop``
branch up-to-date.
.. note:: Closing GitHub issues from commits
This "merge-forward" strategy requires that `the magic keywords to close a
GitHub issue <Closing issues via commit message>`_ appear in the commit
message text directly. Only including the text in a pull request will not
close the issue.
GitHub will close the referenced issue once the *commit* containing the
magic text is merged into the default branch (``develop``). Any magic text
input only into the pull request description will not be seen at the
Git-level when those commits are merged-forward. In other words, only the
commits are merged-forward and not the pull request.
The ``develop`` branch
----------------------
The ``develop`` branch is unstable and bleeding-edge. Pull requests containing
feature additions or non-bug-fix changes should be made against the ``develop``
branch.
The Salt development team will back-port bug fixes made to ``develop`` to the
current release branch if the contributor cannot create the pull request
against that branch.
Keeping Salt Forks in Sync
==========================
Salt is advancing quickly. It is therefore critical to pull upstream changes Salt is advancing quickly. It is therefore critical to pull upstream changes
from master into forks on a regular basis. Nothing is worse than putting in a from upstream into your fork on a regular basis. Nothing is worse than putting
days of hard work into a pull request only to have it rejected because it has hard work into a pull request only to see bunches of merge conflicts because it
diverged too far from master. has diverged too far from upstream.
To pull in upstream changes: .. seealso:: `GitHub Fork a Repo Guide`_
.. code-block:: bash The following assumes ``origin`` is the name of your fork and ``upstream`` is
the name of the main `saltstack/salt`_ repository.
# For ssh github #. View existing remotes.
git remote add upstream git@github.com:saltstack/salt.git
git fetch upstream
# For https github .. code-block:: bash
git remote add upstream https://github.com/saltstack/salt.git
git fetch upstream
git remote -v
To check the log to be sure that you actually want the changes, run the #. Add the ``upstream`` remote.
following before merging:
.. code-block:: bash .. code-block:: bash
git log upstream/develop # For ssh github
git remote add upstream git@github.com:saltstack/salt.git
Then to accept the changes and merge into the current branch: # For https github
git remote add upstream https://github.com/saltstack/salt.git
.. code-block:: bash #. Pull upstream changes into your clone.
git merge upstream/develop .. code-block:: bash
For more info, see `GitHub Fork a Repo Guide`_ or `Open Comparison Contributing git fetch upstream
Docs`_
.. _`GitHub Fork a Repo Guide`: https://help.github.com/articles/fork-a-repo #. Update your copy of the ``develop`` branch.
.. _`Open Comparison Contributing Docs`: http://opencomparison.readthedocs.org/en/latest/contributing.html
.. code-block:: bash
git checkout develop
git merge --ff-only upstream/develop
If Git complains that a fast-forward merge is not possible, you have local
commits.
* Run ``git pull --rebase origin develop`` to rebase your changes on top of
the upstream changes.
* Or, run ``git branch <branch-name>`` to create a new branch with your
commits. You will then need to reset your ``develop`` branch before
updating it with the changes from upstream.
If Git complains that local files will be overwritten, you have changes to
files in your working directory. Run ``git status`` to see the files in
question.
#. Update your fork.
.. code-block:: bash
git push origin develop
#. Repeat the previous two steps for any other branches you work with, such as
the current release branch.
Posting patches to the mailing list Posting patches to the mailing list
----------------------------------- ===================================
Patches will also be accepted by email. Format patches using `git Patches will also be accepted by email. Format patches using `git
format-patch`_ and send them to the `salt-users`_ mailing list. The contributor format-patch`_ and send them to the `salt-users`_ mailing list. The contributor
will then get credit for the patch, and the Salt community will have an archive will then get credit for the patch, and the Salt community will have an archive
of the patch and a place for discussion. of the patch and a place for discussion.
.. _`git format-patch`: https://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html
.. _`saltstack/salt`: https://github.com/saltstack/salt
.. _`GitHub Fork a Repo Guide`: https://help.github.com/articles/fork-a-repo
.. _`Git resources`: https://help.github.com/articles/what-are-other-good-resources-for-learning-git-and-github
.. _`Closing issues via commit message`: https://help.github.com/articles/closing-issues-via-commit-messages
.. _`git format-patch`: https://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html