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

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

@ -1,3 +1,4 @@
============
Contributing
============
@ -5,66 +6,77 @@ 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
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.
For details on how to contribute documentation improvements please review
:ref:`Writing Salt Documentation <salt-docs>`.
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.
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.
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.
#. Fork the `saltstack/salt`_ repository on GitHub.
#. Make a local clone of your fork.
#. Create a new branch in your clone.
First, make a local clone of your GitHub fork of the salt GitHub repo and make
edits and changes locally.
A branch should have one purpose. For example, "Fix bug X," or "Add feature
Y." Multiple pull requests should be opened for unrelated changes.
Then, create a new branch on your clone by entering the following commands:
Choose a name for your branch that describes its purpose.
.. code-block:: bash
git checkout -b fixed-broken-thing
Switched to a new branch 'fixed-broken-thing'
#. Make edits and changes locally.
#. Commit changes to this new branch.
Choose a name for your branch that describes its purpose.
Now commit your changes to this new branch with the following command:
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 commit -am 'description of my fixes for the broken thing'
git add path/to/file1
git add path/to/file2
git commit -m "Fixed X in file1 and file2"
.. note::
If you get stuck `there are many introductory Git resources on
help.github.com <Git resources>`_.
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:
#. Push your locally-committed changes to your GitHub fork.
.. 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.
#. Go to your fork on the GitHub website & find your branch.
Put in a descriptive comment, and include links to any project issues related
to the pull request.
GitHub automatically displays a button with the text "Compare & pull
request" for recently pushed branches.
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.
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.
For details on how to contribute documentation improvements please review
:ref:`Writing Salt Documentation <salt-docs>`.
#. 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
@ -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
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
development team.
GitHub will open pull requests against Salt's main branch named ``develop`` by
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
release, please note in the comments that it should be reviewed
for inclusion.
Each pull request should address a single concern, as mentioned in the section
above. For example, "Fix bug X," or "Add feature Y." And a pull request should
be opened against the branch that corresponds to that concern.
Pull requests that are accepted to Salt but not merged into a minor
release will always be available in the next major release.
Keeping Salt Forks in Sync
The current release branch
--------------------------
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
days of hard work into a pull request only to have it rejected because it has
diverged too far from master.
The current release branch is the most recent stable release. Pull requests
containing bug fixes should be made against the release branch.
To pull in upstream changes:
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
from upstream into your fork on a regular basis. Nothing is worse than putting
hard work into a pull request only to see bunches of merge conflicts because it
has diverged too far from upstream.
.. seealso:: `GitHub Fork a Repo Guide`_
The following assumes ``origin`` is the name of your fork and ``upstream`` is
the name of the main `saltstack/salt`_ repository.
#. View existing remotes.
.. code-block:: bash
git remote -v
#. Add the ``upstream`` remote.
.. code-block:: bash
# For ssh github
git remote add upstream git@github.com:saltstack/salt.git
git fetch upstream
# For https github
git remote add upstream https://github.com/saltstack/salt.git
#. Pull upstream changes into your clone.
.. code-block:: bash
git fetch upstream
To check the log to be sure that you actually want the changes, run the
following before merging:
#. Update your copy of the ``develop`` branch.
.. code-block:: bash
git log upstream/develop
git checkout develop
git merge --ff-only upstream/develop
Then to accept the changes and merge into the current branch:
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 merge upstream/develop
git push origin develop
For more info, see `GitHub Fork a Repo Guide`_ or `Open Comparison Contributing
Docs`_
.. _`GitHub Fork a Repo Guide`: https://help.github.com/articles/fork-a-repo
.. _`Open Comparison Contributing Docs`: http://opencomparison.readthedocs.org/en/latest/contributing.html
#. Repeat the previous two steps for any other branches you work with, such as
the current release branch.
Posting patches to the mailing list
-----------------------------------
===================================
Patches will also be accepted by email. Format patches using `git
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
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