lammps/doc/src/tutorial_github.txt

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

LAMMPS GitHub tutorial :h3
[written by Stefan Paquay]

:line

This document briefly describes how to use GitHub to merge changes you
make into LAMMPS, using GitHub. It assumes that you are familiar with
git. You may want to have a look at the "Git
book"_http://git-scm.com/book/ to reacquaint yourself.

:line

[Making an account]

First of all, you need a GitHub account. This is fairly simple, just
go to "GitHub"_https://github.com and create an account by clicking
the "Sign up for GitHub" button. Once your account is created, you
can sign in by clicking the button in the top left and filling in your
username or e-mail address and password.

:line

[Forking the repository]

To get changes into LAMMPS, you need to first fork the repository. At
the time of writing, master is the preferred branch. Go to "LAMMPS
on GitHub"_https://github.com/lammps/lammps and make sure branch is
set to "master", see the figure below.

:c,image(JPG/tutorial_branch.png)

If it is not, use the button to change it to master. Once it is, use the
fork button to create a fork.

:c,image(JPG/tutorial_fork.png)


This will create your own fork of the LAMMPS repository. You can make
changes in this fork and later file {pull requests} to allow the
upstream repository to merge changes from your own fork into the one
we just forked from. At the same time, you can set things up, so you
can include changes from upstream into your repository.

:line

[Adding changes to your own fork]

Additions to the upstream version of LAMMPS are handled using {feature
branches}.  For every new feature, a so-called feature branch is
created, which contains only those modification relevant to one specific
feature. For example, adding a single fix would consist of creating a
branch with only the fix header and source file and nothing else.  It is
explained in more detail here: "feature branch
workflow"_https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow.

[Feature branches]

First of all, create a clone of your version on github on your local
machine via HTTPS

  $ git clone https://github.com/<your user name>/lammps.git <some name> :pre

or, if you have SSH keys setup, using your SSH key:

  $ git clone git@github.com:<your user name>/lammps.git :pre
  
You can find the proper url by clicking the "Clone or download"-button:

:c,image(JPG/tutorial_https_block.png)

The above command copies ("clones") the git repository to your local
machine to a directory with the name you chose. If none is given, it will
default to "lammps". Typical names are "mylammps" or something similar.

You can use this local clone to make changes and
test them without interfering with the repository on Github.

To pull changes from upstream into this copy, you can go to the directory
and use git pull:

  $ cd mylammps
  $ git checkout master
  $ git pull https://github.com/lammps/lammps :pre

You can also add this url as a remote:

  $ git remote add lammps_upstream https://www.github.com/lammps/lammps :pre

At this point, you typically make a feature branch from the updated master
branch for the feature you want to work on. This tutorial contains the
workflow that updated this tutorial, and hence we will call the branch
"github-tutorial-update":

  $ git checkout -b github-tutorial-update master :pre

Now that we have changed branches, we can make our changes to our local
repository. Just remember that if you want to start working on another,
unrelated feature, you should switch branches!

[After changes are made]

After everything is done, add the files to the branch and commit them:

  $ git add doc/src/tutorial_github.txt
  $ git add doc/src/JPG/tutorial_*.png :pre

IMPORTANT NOTE: Do not use `git commit -a`.  The -a flag will
automatically include _all_ modified or new files and that is rarely the
behavior you want.  It can easily lead to accidentally adding unrelated
and unwanted changes into the repository.  Instead it is preferable to
explicitly use `git add`, `git rm`, `git mv` for adding, removing,
renaming files, respectively, and then `git commit` to finalize the
commit.  If you find doing this on the command line too tedious,
consider using a GUI, for example the one included in git distributions
written in Tk, i.e. use `git gui` (on some Linux distributions it may
be required to install an additional package to use it).

After adding all files, the change set can be committed with some
useful message that explains the change.

  $ git commit -m 'Finally updated the github tutorial' :pre

After the commit, the changes can be pushed to the same branch on GitHub:

$ git push :pre

Git will ask you for your user name and password on GitHub if you have
not configured anything. If your local branch is not present on Github yet,
it will ask you to add it by running

  $ git push --set-upstream origin github-tutorial-update :pre

If you correctly type your user name and
password, the feature branch should be added to your fork on GitHub.

If you want to make really sure you push to the right repository
(which is good practice), you can provide it explicitly:

$ git push origin :pre

or using an explicit URL:

$ git push git@github.com:Pakketeretet2/lammps.git :pre

[Filing a pull request]

Up to this point in the tutorial, all changes were to {your} clones of LAMMPS.
Eventually, however, you want this feature to be included again upstream.
To do this, you will want to file a pull request by clicking on the
"New pull request" button:

:c,image(JPG/tutorial_new_pull_request.png)

Make sure that the current branch is set to the correct one, which, in
this case, is "github-tutorial-update". If done correctly, the only
changes you will see are those that were made on this branch.

This will open up a new window that lists changes made to the
repository. If you are just adding new files, there is not much to do,
but I suppose merge conflicts are to be resolved here if there are
changes in existing files. If all changes can automatically be merged,
green text at the top will say so and you can click the "Create pull
request" button, see image.

:c,image(JPG/tutorial_create_new_pull_request1.png)

Before creating the pull request, make sure the short title is accurate
and add a comment with details about your pull request.
I guess here you write what your modifications do and why they should
be incorporated upstream.

Note the checkbox that says "Allow edits from maintainers".
This is checked by default checkbox (although in my version of Firefox, only the checkmark is visible):

:c,image(JPG/tutorial_edits_maintainers.png)

If it is checked, maintainers can immediately add their own edits to the pull request.
This helps the inclusion of your branch significantly, as simple/trivial changes can be made by the maintainers directly.
The alternative would be that they make changes on their own version of the branch and file a reverse pull request to you.
Just leave this box checked unless you have a very good reason not to.

Now just write some nice comments and click on "Create pull request".

:c,image(JPG/tutorial_create_new_pull_request2.png)

:line

[After filing a pull request]

NOTE: When you submit a pull request (or ask for a pull request), you will receive an
invitation to become a LAMMPS project collaborator. This will simplify certain
administrative tasks and will probably speed up the merging of your feature.

You will notice that after filing the pull request, some checks are performed automatically:

:c,image(JPG/tutorial_automated_checks.png)

If all is fine, you will see this:

:c,image(JPG/tutorial_automated_checks_passed.png)

A few further interesting things (can) happen to pull requests before they are included.

[Additional changes]

First of all, any additional changes you push into your branch in your
repository will automatically become part of the pull request:

:c,image(JPG/tutorial_additional_changes.png)

This means you can add changes that should be part of the feature after
filing the pull request, which is useful in case you have forgotten
them, or if a developer has ruled that something needs to change before
the feature can be accepted upstream.  After each push, the automated
checks are run again.

[Assignees]

There is an assignee label for pull requests. If the request has not
been reviewed by any developer yet, it is not assigned to anyone. After
revision, a developer can choose to assign it to either a) you, b) a
LAMMPS developer (including him/herself) or c) Steve Plimpton (sjplimp).

Case a) happens if changes are required on your part :ulb,l
Case b) means that at the moment, it is being tested and reviewed by a
LAMMPS developer.  After review, the developer can choose to implement
changes or suggest them to you. :l
Case c) means that the pull request has been assigned to the lead
developer Steve Plimpton, and means it is considered ready for
merging. :ule,l

In this case, Axel assigned the tutorial to Steve:

:c,image(JPG/tutorial_steve_assignee.png)

[Edits from LAMMPS maintainers]

If you allowed edits from maintainers (the default), any LAMMPS maintainer can add changes to your pull request.
In this case, both Axel and Richard made changes to the tutorial:

:c,image(JPG/tutorial_changes_others.png)

:line

[After a merge]

When everything is fine, the feature branch is merged into the master branch.

:c,image(JPG/tutorial_merged.png)

Now one question remains: What to do with the feature branch that got
merged into upstream?

It is in principle safe to delete them from your own fork. This helps
keep it a bit more tidy. Note that you first have to switch to another
branch!

$ git checkout master
$ git pull master
$ git branch -d github-tutorial-update :pre

If you do not pull first, it is not really a problem but git will warn
you at the next statement that you are deleting a local branch that
was not yet fully merged into HEAD. This is because git does not yet
know your branch just got merged into lammps-icms upstream. If you
first delete and then pull, everything should still be fine.

Finally, if you delete the branch locally, you might want to push this
to your remote(s) as well:

$ git push origin :github-tutorial-update :pre

[Recent changes in the workflow]

Some changes to the workflow are not captured in this tutorial.
For example, in addition to the master branch, to which all
new features should be submitted, there is now also an "unstable"
and a "stable" branch. Furthermore, the naming of the patches
now follow the pattern "patch_<Day><Month><Year>" so simplify
comparisons between releases.
Finally, all patches and submissions are subject to automatic
testing and code checks to make sure they at the very least
compile.