Thanks to visit codestin.com
Credit goes to github.com

Skip to content

#133: Update Devguide pull request commit documentation #134

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

#133: Update Devguide pull request commit documentation #134

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 65 additions & 5 deletions pullrequest.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,18 +137,78 @@ changes to your PR.
Submitting
----------

Once you are satisfied with your work you will want to commit your
changes to your branch. In general you can run ``git commit -a`` and
that will commit everything. You can always run ``git status`` to see
what changes are outstanding.
Once you are satisfied with your work, you will need to commit your
changes to your branch. Assume you want to add a file which you have changed,
you will need to enter this command::
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is confusing. If I changed a file, the file was probably there already, so I don't need to add it.
I think this part about git add can be removed, for the following reasons:

  1. Adding files is uncommon -- most of the times existing files are changed
  2. If the file is not added, I believe git will give an error during commit
  3. The command to add files is very simple and similar for all the VCS

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ezio-melotti I'm confused about your comments. It's a common workflow pattern with git to:

git add <files>
git commit -m 'Commit message here'

Copy link
Member

@ezio-melotti ezio-melotti Mar 1, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apparently I assumed this worked like Mercurial, but it doesn't...

So git add doesn't mean "add this file to the tracked files starting from the next commit", but something like "add this file to the list of files that will get committed when I do git commit, right?
Also will git commit -am include all the modified files, including new files that were previously untracked?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

git add will add files (modified or new) to the staging area. Files in the staging area will be committed when git commit is issued.

-a modifier will only include modified files and deleted files (it will not add new untracked) https://git-scm.com/docs/git-commit Plenty of folks use -a; I just prefer the more conservative two step git add git commit -m.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think it would then be ok to suggest git command -am '...'?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's better practice to use -m, but I'm happy to defer to you and Berker on that.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

personally speaking, I usually use -v option. Then I do final self review and write commit message in vim.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't sure if we were using git description? If yes, we are using description, I think we should mention git commit, because this will open the editor and let user to enter title and description.

If not, I think using git commit -m is fine.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would keep git status, and perhaps mention it together with git diff as both are useful to check if the right thing is being committed.


git add <file>

After adding all the files that you changed, you can commit them with::

git commit -m

The commit message's title should start with
``bpo-NNNNN`` and the major change of this commit, for example::

bpo-29624: Adds purge step and layout test after uploading files.

Combine with `git commit -m`, it should be::

git commit -m "bpo-29624: Adds purge step and layout test after uploading files."

Two commands, ``git status`` and ``git diff``, provide helpful information
and details about commits and changes.::

git status

On branch pr_133
Your branch and 'origin/pr_133' have diverged,
and have 14 and 2 different commits each, respectively.
(use "git pull" to merge the remote branch into yours)
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

modified: pullrequest.rst

no changes added to commit (use "git add" and/or "git commit -a")

git diff

diff --git a/pullrequest.rst b/pullrequest.rst
index daa419c..cb32aad 100644
--- a/pullrequest.rst
+++ b/pullrequest.rst
@@ -143,27 +143,44 @@ you will need to enter this command::

git add <file>

-After adding all files of changed, you can commit your changes::
+After adding all the files that you changed, you can commit them with::


.. note::

You will see the references PR number at the end of the title in `git log`,
e.g.
「bpo-29624: Adds purge step and layout test after uploading files.
**(#258)**」, you won't need to add this into your commit title, it will
be automatically added when making a pull request on GitHub website.

When all of your changes are committed (i.e. ``git status`` doesn't
list anything), you will want to push your branch to your fork::
list anything), you will need to push your branch to your fork::

git push origin <branch name>

This will get your changes up to GitHub.

.. seealso::

For more information about Git commands, please refer to:

* `Git Cheat Sheet <https://services.github.com/on-demand/downloads/github-git-cheat-sheet.pdf>`_
* `ProGit <https://git-scm.com/book/en/v2>`_

Now you want to
`create a pull request from your fork <https://help.github.com/articles/creating-a-pull-request-from-a-fork/>`_.
If this is a pull request in response to a pre-existing issue on the
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure the correct flow for a GitHub PR, still have some question here.

Because we will need the bpo id for commit title, should the above content about creating bpo issue put to the front of the chapter? Or the contributor maybe confuse about bpo title we mention before.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it should be moved earlier, and mention that creating an issue is not necessary for trivial changes.

Expand Down