ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Finally updated the github tutorial.

Browse Source
This commit is contained in:
Stefan Paquay
2017-01-02 17:55:02 +01:00
parent 62dea1bb63
commit 391ab761a4
4 changed files with 50 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
doc/src/tutorial_github.txt
View File

@ -31,16 +31,18 @@ username or e-mail address and password.
[Forking the repository]
To get changes into LAMMPS, you need to first fork the repository. At
the time of writing, LAMMPS-ICMS is the preferred fork. Go to "LAMMPS
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 "lammps-icms", see the figure below.
set to "master", see the figure below.
:c,image(JPG/tutorial_branch.png)
Now, click on fork in the top right corner:
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
@ -51,67 +53,63 @@ can include changes from upstream into your repository.
[Adding changes to your own fork]
Before adding changes, it is better to first create a new branch that
will contain these changes, a so-called feature branch.
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]
Since LAMMPS is such a big project and most user contributions come in
small portions, the most ideal workflow for LAMMPS is the so-called
"Feature branch" workflow. It is explained in great detail here:
"feature branch
workflow"_https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow.
First of all, create a clone of your version on github on your local machine via HTTPS
The idea is that every new feature for LAMMPS gets its own
branch. This way, it is fairly painless to incorporate new features
into the upstream repository. I will explain briefly here how to do
it. In this feature branch, I will add a USER-package.
$ git clone https://github.com/<your user name>/lammps.git <some name> :pre
I assume that git is installed on the local machine and you know how
to use a command line.
or, if you have SSH keys setup, using your SSH key:
First of all, you need to clone your own fork of LAMMPS:
$ git clone https://github.com/<your user name>/lammps.git :pre
You can find the proper url to the right of the "HTTPS" block, see figure.
$ 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. You can use this local clone to make changes and test them
without interfering with the repository on github. First, however, it
is recommended to make a new branch for a particular feature you would
like added to LAMMPS. In this example, I will try adding a new
USER-package called USER-MANIFOLD.
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.
To create a new branch, run the following git command in your repository:
You can use this local clone to make changes and
test them without interfering with the repository on Github.
$ git checkout -b add-user-manifold :pre
To pull changes from upstream into this copy, you can go to the directory
and use git pull:
The name of this new branch is "add-user-manifold" in my case. Just
name it after something that resembles the feature you want added to
LAMMPS.
$ cd mylammps :pre
$ git pull https://github.com/lammps/lammps :pre
Now that you've changed branches, you can edit the files as you see
fit, add new files, and commit as much as you would like. Just
remember that if halfway you decide to add another, unrelated feature,
you should switch branches!
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 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 :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 src/USER-MANIFOLD examples/USER/manifold/
$ git add doc/fix_nv\{t,e\}_manifold_rattle.txt
$ git add doc/fix_manifoldforce.txt doc/user_manifolds.txt :pre
$ git add doc/src/tutorial_github.txt :pre
$ git add doc/src/JPG/tutorial_*.png :pre
After the files are added, the change should be comitted:
$ git commit -m 'Added user-manifold package' :pre
The "-m" switch is used to add a message to the commit. Use this to
indicate what type of change was commited.
[Wisdom by Axel]
[Warning]
{"Do not use "git commit -a". the -a flag will automatically include
*all* modified or new files. mercurial does that and it find it
@ -121,7 +119,12 @@ renaming and then git commit to finalize the commit. personally, i
find it very convenient to use the bundled gui for commits, i.e. git
gui. typically, i will do git add and other operations, but then
verify and review them with git gui. git gui also allows to do
line-by-line unstaging and other convenient operations."}
line-by-line unstaging and other convenient operations." - Axel}
After adding all files, the change can be commited 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:
@ -140,75 +143,3 @@ or using an explicit URL:
$ git push git@github.com:Pakketeretet2/lammps.git :pre
After that, you can file a new pull request based on this
branch. GitHub will now look like this:
:c,image(JPG/tutorial_pull_request_feature_branch1.png)
Make sure that the current branch is set to the correct one, which, in
this case, is "add-user-manifold". Now click "New pull request". If
done correctly, the only changes you will see are those that were made
on this branch, so in my case, I will see nothing related to
$\mathrm{pair\_dzugatov}.$
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_pull_request2.png)
After this you have to specify a short title and a comment with
details about your pull request. I guess here you write what your
modifications do and why they should be incorporated upstream. After
that, click the "Create pull request" button, see image below.
:c,image(JPG/tutorial_pull_request3.png)
Now just write some nice comments, click "Comment", and that is it. It
is now up to the maintainer(s) of the upstream repository to
incorporate the changes into the repository and to close the pull
request.
:c,image(JPG/tutorial_pull_request4.png)
:line
[Additional changes]
Before the pull request is accepted, any additional changes you push
into your repository will automatically become part of the pull
request.
:line
[After a merge]
When everything is fine the feature branch is merged into the LAMMPS
repositories:
: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 lammps-icms
$ git pull lammps-icms
$ git branch -d add-user-manifold :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 :add-user-manifold :pre