update and reorder the description of the process for submitting contributions
This commit is contained in:
Axel Kohlmeyer
@ -9,7 +9,8 @@ this.
|
||||
If you add a new feature to LAMMPS and think it will be of interest to
|
||||
general users, we encourage you to submit it for inclusion in LAMMPS
|
||||
as a pull request on our `GitHub site <https://github.com/lammps/lammps>`_,
|
||||
after reading :doc:`this page <Modify_contribute>`.
|
||||
after reading about :doc:`how to prepare your code for submission <Modify_contribute>`
|
||||
and :doc:`the style requirements and recommendations <Modify_style>`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
@ -1,22 +1,20 @@
|
||||
Submitting new features for inclusion in LAMMPS
|
||||
===============================================
|
||||
|
||||
We encourage users to submit new features or modifications for LAMMPS to
|
||||
`the core developers <https://www.lammps.org/authors.html>`_ so they can
|
||||
be added to the LAMMPS distribution. The preferred way to manage and
|
||||
coordinate this is via the LAMMPS project on `GitHub
|
||||
<https://github.com/lammps/lammps>`_. Please see the :doc:`GitHub
|
||||
Tutorial <Howto_github>` for a demonstration on how to do that. An
|
||||
alternative is to contact the LAMMPS developers or the indicated
|
||||
developer of a package or feature directly and send in your contribution
|
||||
via e-mail, but that can add a significant delay on getting your
|
||||
contribution included, depending on how busy the respective developer
|
||||
is, how complex a task it would be to integrate that code, and how
|
||||
many - if any - changes are required before the code can be included.
|
||||
We encourage LAMMPS users to submit new features they wrote for LAMMPS
|
||||
to be included into the LAMMPS distribution and thus become easily
|
||||
accessible to all LAMMPS users. The LAMMPS source code is managed with
|
||||
git and public development is hosted on `GitHub
|
||||
<https://github.com/lammps/lammps>`_. You can monitor the repository to
|
||||
be notified of releases, follow the ongoing development, and comment on
|
||||
topics of interest to you.
|
||||
|
||||
Communication with the LAMMPS developers
|
||||
----------------------------------------
|
||||
|
||||
For any larger modifications or programming project, you are encouraged
|
||||
to contact the LAMMPS developers ahead of time in order to discuss
|
||||
implementation strategies and coding guidelines. That will make it
|
||||
implementation strategies and coding guidelines. That will make it
|
||||
easier to integrate your contribution and results in less work for
|
||||
everybody involved. You are also encouraged to search through the list
|
||||
of `open issues on GitHub <https://github.com/lammps/lammps/issues>`_
|
||||
@ -26,43 +24,84 @@ duplicated by others.
|
||||
|
||||
For informal communication with the LAMMPS developers you may ask to
|
||||
join the `LAMMPS developers on Slack <https://lammps.slack.com>`_. This
|
||||
slack work space is by invitation only. Thus for access, please send an
|
||||
slack work space is by invitation only. Thus for access, please send an
|
||||
e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you are
|
||||
working on. Only discussions related to LAMMPS development are
|
||||
tolerated, so this is **NOT** for people that look for help with
|
||||
compiling, installing, or using LAMMPS. Please post a message to the
|
||||
`lammps-users mailing list <https://www.lammps.org/mail.html>`_ or the
|
||||
`LAMMPS forum <https://www.lammps.org/forum.html>`_ for those purposes.
|
||||
tolerated in that workspace, so this is **NOT** for people that look for
|
||||
help with compiling, installing, or using LAMMPS. Please post a message
|
||||
to the `lammps-users mailing list <https://www.lammps.org/mail.html>`_
|
||||
or the `LAMMPS forum <https://www.lammps.org/forum.html>`_ for those
|
||||
purposes.
|
||||
|
||||
How quickly your contribution will be integrated depends largely on how
|
||||
much effort it will cause to integrate and test it, how many and what
|
||||
kind of changes it requires to the core codebase, and of how much
|
||||
Packages versus individual files
|
||||
--------------------------------
|
||||
|
||||
The remainder of this chapter describes how to add new "style" files of
|
||||
various kinds to LAMMPS. Packages are simply collections of one or more
|
||||
such new class files which are invoked as a new style within a LAMMPS
|
||||
input script. In some cases also collections of supporting functions or
|
||||
classes are included as separate files in a package, especially when
|
||||
they can be shared between multiple styles. If designed correctly, these
|
||||
additions typically do not require any changes to the core code of
|
||||
LAMMPS; they are simply add-on files that are compiled with the rest of
|
||||
LAMMPS. To make those styles work, you may need some trivial changes to
|
||||
the core code; an example of a trivial change is making a parent-class
|
||||
method "virtual" when you derive a new child class from it.
|
||||
|
||||
If you think your new feature or package requires some non-trivial
|
||||
changes in core LAMMPS files, you should communicate with the LAMMPS
|
||||
developers `on Slack <https://lammps.org/slack.html>`_, `on GitHub
|
||||
<https://github.com/lammps/lammps/issues>`_, or `via email
|
||||
<https://www.lammps.org/authors.html>`_, since we may have
|
||||
recommendations about what changes to do where, or may not want to
|
||||
include certain changes for some reason and thus you would need to look
|
||||
for alternatives.
|
||||
|
||||
Time and effort required
|
||||
------------------------
|
||||
|
||||
How quickly your contribution will be integrated can vary a lot. It
|
||||
depends largely on how much effort it will cause the LAMMPS developers
|
||||
to integrate and test it, how many and what kind of changes to the core
|
||||
code are required, how quickly you can address them and of how much
|
||||
interest it is to the larger LAMMPS community. Please see the section
|
||||
on :doc:`LAMMPS programming style and requirements <Modify_style>` for
|
||||
instructions, recommendations, and requirements.
|
||||
instructions, recommendations, and formal requirements. A small,
|
||||
modular, well written contribution may be integrated within hours, but a
|
||||
complex change that will require a redesign of some core functionality
|
||||
in LAMMPS for a clean integration can take many months until it is
|
||||
considered ready for inclusion (though this is rare).
|
||||
|
||||
|
||||
Submission procedure
|
||||
--------------------
|
||||
|
||||
All changes to LAMMPS (including those from LAMMPS developers) are
|
||||
integrated via pull requests on GitHub and cannot be merged without
|
||||
passing the automated testing and an approving review by a LAMMPS core
|
||||
developer. Thus before submitting your contribution, you should first
|
||||
make certain, that your added or modified code compiles and works
|
||||
correctly with the latest patch-level or development version of LAMMPS
|
||||
and contains all bug fixes from it.
|
||||
|
||||
Once you have prepared everything, see the :doc:`LAMMPS GitHub Tutorial
|
||||
<Howto_github>` page for instructions on how to submit your changes or
|
||||
new files through a GitHub pull request. If you are unable or unwilling
|
||||
to submit via GitHub yourself, you may also submit patch files or full
|
||||
files to the LAMMPS developers and ask them to submit a pull request on
|
||||
GitHub on your behalf. **All** changes to LAMMPS (including those from
|
||||
the LAMMPS core developers) must be submitted as GitHub pull requests
|
||||
and cannot be merged without passing the automated integration and unit
|
||||
testing as well as a code review by a LAMMPS core developer that did not
|
||||
submit it. Thus before submitting your contribution, you should first
|
||||
make certain, that your added or modified code works correctly with the
|
||||
latest patch-level version of LAMMPS and contains all bug fixes from it.
|
||||
Then create a gzipped tar file of all changed or added files or a
|
||||
corresponding patch file using 'diff -u' or 'diff -c' and compress it
|
||||
with gzip. Please only use gzip compression, as this works well and is
|
||||
available on all platforms.
|
||||
new files through a GitHub pull request yourself. If you are unable or
|
||||
unwilling to submit via GitHub yourself, you may also submit patch files
|
||||
or full files to the LAMMPS developers and ask them to submit a pull
|
||||
request on GitHub on your behalf. Then create a gzipped tar file of
|
||||
all changed or added files or a corresponding patch file using
|
||||
'diff -u' or 'diff -c' format and compress it with gzip. Please only
|
||||
use gzip compression, as this works well and is available on all platforms.
|
||||
|
||||
If the new features/files are broadly useful we may add them as core
|
||||
files to LAMMPS or as part of a :doc:`package <Packages_list>`. All
|
||||
packages are listed and described on the :doc:`Packages details
|
||||
<Packages_details>` doc page.
|
||||
|
||||
Licensing
|
||||
---------
|
||||
|
||||
Note that by providing us files to release, you agree to make them
|
||||
open-source, i.e. we can release them under the terms of the GPL
|
||||
(version 2) with the rest of LAMMPS. And similarly as part of a LGPL
|
||||
@ -71,30 +110,17 @@ developers on request only and with files that are not authorized for
|
||||
that kind of distribution removed (e.g. interface to FFTW). See the
|
||||
:doc:`LAMMPS license <Intro_opensource>` page for details.
|
||||
|
||||
.. note::
|
||||
External contributions
|
||||
----------------------
|
||||
|
||||
If you prefer to do so, you can also develop and support your add-on
|
||||
feature without having it included in the LAMMPS distribution, for
|
||||
example as a download from a website of your own. See the `Offsite
|
||||
LAMMPS packages and tools <https://www.lammps.org/offsite.html>`_
|
||||
page of the LAMMPS website for examples of groups that do this. We
|
||||
are happy to advertise your package and website from that page.
|
||||
Simply email the `developers <https://www.lammps.org/authors.html>`_
|
||||
with info about your package and we will post it there. We recommend
|
||||
to name external packages USER-\<name\> so they can be easily
|
||||
distinguished from bundled packages that do not have the USER-
|
||||
prefix.
|
||||
If you prefer to do so, you can also develop and support your add-on
|
||||
feature **without** having it included in the LAMMPS distribution, for
|
||||
example as a download from a website of your own. See the `Offsite
|
||||
LAMMPS packages and tools <https://www.lammps.org/offsite.html>`_ page
|
||||
of the LAMMPS website for examples of groups that do this. We are happy
|
||||
to advertise your package and website from that page. Simply email the
|
||||
`developers <https://www.lammps.org/authors.html>`_ with info about your
|
||||
package and we will post it there. We recommend to name external
|
||||
packages USER-\<name\> so they can be easily distinguished from bundled
|
||||
packages that do not have the USER- prefix.
|
||||
|
||||
.. _lws: https://www.lammps.org
|
||||
|
||||
The previous sections of this page describe how to add new "style"
|
||||
files of various kinds to LAMMPS. Packages are simply collections of
|
||||
one or more new class files which are invoked as a new style within a
|
||||
LAMMPS input script. If designed correctly, these additions typically
|
||||
do not require changes to the main core of LAMMPS; they are simply
|
||||
add-on files. If you think your new feature requires non-trivial
|
||||
changes in core LAMMPS files, you should `communicate with the
|
||||
developers <https://www.lammps.org/authors.html>`_, since we may or
|
||||
may not want to include those changes for some reason. An example of a
|
||||
trivial change is making a parent-class method "virtual" when you derive
|
||||
a new child class from it.
|
||||
|
||||
Reference in New Issue
Block a user