diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 54cb975723..182dd302b6 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -5,8 +5,9 @@ Thank your for considering to contribute to the LAMMPS software project. The following is a set of guidelines as well as explanations of policies and work flows for contributing to the LAMMPS molecular dynamics software project. These guidelines focus on submitting issues or pull requests on the LAMMPS GitHub project. Thus please also have a look at: -* [The Section on submitting new features for inclusion in LAMMPS of the Manual](https://lammps.sandia.gov/doc/Modify_contribute.html) -* [The LAMMPS GitHub Tutorial in the Manual](http://lammps.sandia.gov/doc/Howto_github.html) +* [The guide for submitting new features in the LAMMPS manual](https://lammps.sandia.gov/doc/Modify_contribute.html) +* [The guide on programming style and requirement in the LAMMPS manual](https://lammps.sandia.gov/doc/Modify_contribute.html) +* [The GitHub tutorial in the LAMMPS manual](http://lammps.sandia.gov/doc/Howto_github.html) ## Table of Contents @@ -26,11 +27,11 @@ __ ## I don't want to read this whole thing I just have a question! -> **Note:** Please do not file an issue to ask a general question about LAMMPS, its features, how to use specific commands, or how perform simulations or analysis in LAMMPS. Instead post your question to either the ['lammps-users' mailing list](https://lammps.sandia.gov/mail.html) or the [LAMMPS Material Science Discourse forum](https://matsci.org/lammps). You do not need to be subscribed to post to the list (but a mailing list subscription avoids having your post delayed until it is approved by a mailing list moderator). Most posts to the mailing list receive a response within less than 24 hours. Before posting to the mailing list, please read the [mailing list guidelines](https://lammps.sandia.gov/guidelines.html). Following those guidelines will help greatly to get a helpful response. Always mention which LAMMPS version you are using. The LAMMPS forum was recently created as part of a larger effort to build a materials science community and have discussions not just about using LAMMPS. Thus the forum may be also used for discussions that would be off-topic for the mailing list. Those will just have to be moved to a more general category. +> **Note:** Please do not file an issue to ask a general question about LAMMPS, its features, how to use specific commands, or how perform simulations or analysis in LAMMPS. Instead post your question to either the ['lammps-users' mailing list](https://lammps.sandia.gov/mail.html) or the [LAMMPS Material Science Discourse forum](https://matsci.org/lammps). You do not need to be subscribed to post to the list (but a mailing list subscription avoids having your post delayed until it is approved by a mailing list moderator). Most posts to the mailing list receive a response within less than 24 hours. Before posting to the mailing list, please read the [mailing list guidelines](https://lammps.sandia.gov/guidelines.html). Following those guidelines will help greatly to get a helpful response. Always mention which LAMMPS version you are using. The LAMMPS forum was recently created as part of a larger effort to build a materials science community and have discussions not just about using LAMMPS. Thus the forum may be also used for discussions that would be off-topic for the mailing list. Those will just have to be posted to a more general category. ## How Can I Contribute? -There are several ways how you can actively contribute to the LAMMPS project: you can discuss compiling and using LAMMPS, and solving LAMMPS related problems with other LAMMPS users on the lammps-users mailing list, you can report bugs or suggest enhancements by creating issues on GitHub (or posting them to the lammps-users mailing list or posting in the LAMMPS Materials Science Discourse forum), and you can contribute by submitting pull requests on GitHub or e-mail your code +There are several ways how you can actively contribute to the LAMMPS project: you can discuss compiling and using LAMMPS, and solving LAMMPS related problems with other LAMMPS users on the lammps-users mailing list or the forum, you can report bugs or suggest enhancements by creating issues on GitHub (or posting them to the lammps-users mailing list or posting in the LAMMPS Materials Science Discourse forum), and you can contribute by submitting pull requests on GitHub or e-mail your code to one of the [LAMMPS core developers](https://lammps.sandia.gov/authors.html). As you may see from the aforementioned developer page, the LAMMPS software package includes the efforts of a very large number of contributors beyond the principal authors and maintainers. ### Discussing How To Use LAMMPS @@ -62,37 +63,12 @@ To be able to submit an issue on GitHub, you have to register for an account (fo ### Contributing Code -We encourage users to submit new features or modifications for LAMMPS to the core developers so they can be added to the LAMMPS distribution. The preferred way to manage and coordinate this is by submitting a pull request at the LAMMPS project on GitHub. 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 easier to integrate your contribution and result in less work for everybody involved. You are also encouraged to search through the list of open issues on GitHub and submit a new issue for a planned feature, so you would not duplicate the work of others (and possibly get scooped by them) or have your work duplicated by others. +We encourage users to submit new features or modifications for LAMMPS. Instructions, guidelines, requirements, +and recommendations are in the following sections of the LAMMPS manual: +* [The guide for submitting new features in the LAMMPS manual](https://lammps.sandia.gov/doc/Modify_contribute.html) +* [The guide on programming style and requirement in the LAMMPS manual](https://lammps.sandia.gov/doc/Modify_contribute.html) +* [The GitHub tutorial in the LAMMPS manual](http://lammps.sandia.gov/doc/Howto_github.html) -How quickly your contribution will be integrated depends largely on how much effort it will cause to integrate and test it, how much it requires changes to the core code base, and of how much interest it is to the larger LAMMPS community. Please see below for a checklist of typical requirements. Once you have prepared everything, see [this tutorial](https://lammps.sandia.gov/doc/Howto_github.html) - for instructions on how to submit your changes or new files through a GitHub pull request - -Here is a checklist of steps you need to follow to submit a single file or user package for our consideration. Following these steps will save both you and us time. See existing files in packages in the source directory for examples. If you are uncertain, please ask on the lammps-users mailing list. - -* C++ source code must be compatible with the C++-11 standard. Packages may require a later standard, if justified. -* All source files you provide must compile with the most current version of LAMMPS with multiple configurations. In particular you need to test compiling LAMMPS from scratch with `-DLAMMPS_BIGBIG` set in addition to the default `-DLAMMPS_SMALLBIG` setting. Your code will need to work correctly in serial and in parallel using MPI. -* For consistency with the rest of LAMMPS and especially, if you want your contribution(s) to be added to main LAMMPS code or one of its standard packages, it needs to be written in a style compatible with other LAMMPS source files. This means: 2-character indentation per level, no tabs, no trailing whitespace, no lines over 80 characters. I/O is done via the C-style stdio library, style class header files should not import any system headers, STL containers should be avoided in headers, and forward declarations used where possible or needed. All added code should be placed into the LAMMPS_NS namespace or a sub-namespace; global or static variables should be avoided, as they conflict with the modular nature of LAMMPS and the C++ class structure. There MUST NOT be any "using namespace XXX;" statements in headers. In the implementation file (.cpp) system includes should be placed in angular brackets (<>) and for c-library functions the C++ style header files should be included ( instead of , or instead of ). This all is so the developers can more easily understand, integrate, and maintain your contribution and reduce conflicts with other parts of LAMMPS. This basically means that the code accesses data structures, performs its operations, and is formatted similar to other LAMMPS source files, including the use of the error class for error and warning messages. -* Source, style name, and documentation file should follow the following naming convention: style names should be lowercase and words separated by a forward slash; for a new fix style 'foo/bar', the class should be named FixFooBar, the name of the source files should be 'fix_foo_bar.h' and 'fix_foo_bar.cpp' and the corresponding documentation should be in a file 'fix_foo_bar.rst'. -* If you want your contribution to be added as a user-contributed feature, and it is a single file (actually a `.cpp` and `.h` file) it can be rapidly added to the USER-MISC directory. Include the one-line entry to add to the USER-MISC/README file in that directory, along with the 2 source files. You can do this multiple times if you wish to contribute several individual features. -* If you want your contribution to be added as a user-contribution and it is several related features, it is probably best to make it a user package directory with a name like FOO. In addition to your new files, the directory should contain a README text file. The README should contain your name and contact information and a brief description of what your new package does. If your files depend on other LAMMPS style files also being installed (e.g. because your file is a derived class from the other LAMMPS class), then an Install.sh file is also needed to check for those dependencies. See other README and Install.sh files in other USER directories as examples. Send us a tarball of this FOO directory. -* Your new source files need to have the LAMMPS copyright, GPL notice, and your name and email address at the top, like other user-contributed LAMMPS source files. They need to create a class that is inside the LAMMPS namespace. If the file is for one of the USER packages, including USER-MISC, then we are not as picky about the coding style (see above). I.e. the files do not need to be in the same stylistic format and syntax as other LAMMPS files, though that would be nice for developers as well as users who try to read your code. -* You **must** also create or extend a documentation file for each new command or style you are adding to LAMMPS. For simplicity and convenience, the documentation of groups of closely related commands or styles may be combined into a single file. This will be one file for a single-file feature. For a package, it might be several files. These are files in the [reStructuredText](https://docutils.sourceforge.io/rst.html) markup language, that are then converted to HTML and PDF. The tools for this conversion are included in the source distribution, and the translation can be as simple as doing "make html pdf" in the doc folder. Thus the documentation source files must be in the same format and style as other `.rst` files in the lammps/doc/src directory for similar commands and styles; use one or more of them as a starting point. An introduction to reStructuredText can be found at [https://docutils.sourceforge.io/docs/user/rst/quickstart.html](https://docutils.sourceforge.io/docs/user/rst/quickstart.html). The text files can include mathematical expressions and symbol in ".. math::" sections or ":math:" expressions or figures (see doc/JPG for examples), or even additional PDF files with further details (see doc/PDF for examples). The doc page should also include literature citations as appropriate; see the bottom of doc/fix_nh.rst for examples and the earlier part of the same file for how to format the cite itself. The "Restrictions" section of the doc page should indicate that your command is only available if LAMMPS is built with the appropriate USER-MISC or FOO package. See other user package doc files for examples of how to do this. The prerequisite for building the HTML format files are Python 3.x and virtualenv. Please run at least `make html`, `make pdf` and `make spelling` and carefully inspect and proofread the resulting HTML format doc page as well as the output produced to the screen. Make sure that all spelling errors are fixed or the necessary false positives are added to the `doc/utils/sphinx-config/false_positives.txt` file. For new styles, those usually also need to be added to lists on the respective overview pages. This can be checked for also with `make style_check`. -* For a new package (or even a single command) you should include one or more example scripts demonstrating its use. These should run in no more than a couple minutes, even on a single processor, and not require large data files as input. See directories under examples/PACKAGES for examples of input scripts other users provided for their packages. These example inputs are also required for validating memory accesses and testing for memory leaks with valgrind -* For new utility functions or class (i.e. anything that does not depend on a LAMMPS object), new unit tests should be added to the unittest tree. -* When adding a new LAMMPS style, a .yaml file with a test configuration and reference data should be added for the styles where a suitable tester program already exists (e.g. pair styles, bond styles, etc.). -* If there is a paper of yours describing your feature (either the algorithm/science behind the feature itself, or its initial usage, or its implementation in LAMMPS), you can add the citation to the .cpp source file. See src/EFF/atom_vec_electron.cpp for an example. A LaTeX citation is stored in a variable at the top of the file and a single line of code that references the variable is added to the constructor of the class. Whenever a user invokes your feature from their input script, this will cause LAMMPS to output the citation to a log.cite file and prompt the user to examine the file. Note that you should only use this for a paper you or your group authored. E.g. adding a cite in the code for a paper by Nose and Hoover if you write a fix that implements their integrator is not the intended usage. That kind of citation should just be in the doc page you provide. - -Finally, as a general rule-of-thumb, the more clear and self-explanatory you make your documentation and README files, and the easier you make it for people to get started, e.g. by providing example scripts, the more likely it is that users will try out your new feature. - -If the new features/files are broadly useful we may add them as core files to LAMMPS or as part of a standard package. Else we will add them as a user-contributed file or package. Examples of user packages are in src sub-directories that start with USER. The USER-MISC package is simply a collection of (mostly) unrelated single files, which is the simplest way to have your contribution quickly added to the LAMMPS distribution. You can see a list of the both standard and user packages by typing "make package" in the LAMMPS src directory. - -Note that by providing us files to release, you are agreeing to make them open-source, i.e. we can release them under the terms of the GPL, used as a license for the rest of LAMMPS. See Section 1.4 for details. - -With user packages and files, all we are really providing (aside from the fame and fortune that accompanies having your name in the source code and on the Authors page of the LAMMPS WWW site), is a means for you to distribute your work to the LAMMPS user community, and a mechanism for others to easily try out your new feature. This may help you find bugs or make contact with new collaborators. Note that you are also implicitly agreeing to support your code which means answer questions, fix bugs, and maintain it if LAMMPS changes in some way that breaks it (an unusual event). - -To be able to submit an issue on GitHub, you have to register for an account (for GitHub in general). If you do not want to do that, or have other reservations or difficulties to submit a pull request, you can - as an alternative - contact one or more of the core LAMMPS developers and ask if one of them would be interested in manually merging your code into LAMMPS and send them your source code. Since the effort to merge a pull request is a small fraction of the effort of integrating source code manually (which would usually be done by converting the contribution into a pull request), your chances to have your new code included quickly are the best with a pull request. - -If you prefer to submit patches or full files, you should first make certain, that your 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 on all platforms. ## GitHub Workflows @@ -102,17 +78,17 @@ This section briefly summarizes the steps that will happen **after** you have su After submitting an issue, one or more of the LAMMPS developers will review it and categorize it by assigning labels. Confirmed bug reports will be labeled `bug`; if the bug report also contains a suggestion for how to fix it, it will be labeled `bugfix`; if the issue is a feature request, it will be labeled `enhancement`. Other labels may be attached as well, depending on which parts of the LAMMPS code are affected. If the assessment is, that the issue does not warrant any changes, the `wontfix` label will be applied and if the submission is incorrect or something that should not be submitted as an issue, the `invalid` label will be applied. In both of the last two cases, the issue will then be closed without further action. -For feature requests, what happens next is that developers may comment on the viability or relevance of the request, discuss and make suggestions for how to implement it. If a LAMMPS developer or user is planning to implement the feature, the issue will be assigned to that developer. For developers, that are not yet listed as LAMMPS project collaborators, they will receive an invitation to be added to the LAMMPS project as a collaborator so they can get assigned. If the requested feature or enhancement is implemented, it will usually be submitted as a pull request, which will contain a reference to the issue number. And once the pull request is reviewed and accepted for inclusion into LAMMPS, the issue will be closed. For details on how pull requests are processed, please see below. +For feature requests, what happens next is that developers may comment on the viability or relevance of the request, discuss and make suggestions for how to implement it. If a LAMMPS developer or user is planning to implement the feature, the issue will be assigned to that developer. For developers, that are not yet listed as LAMMPS project collaborators, they will receive an invitation to be added to the LAMMPS project as a collaborator so they can get assigned. If the requested feature or enhancement is implemented, it will be submitted as a pull request, which will contain a reference to the issue number. And once the pull request is reviewed and accepted for inclusion into LAMMPS, the issue will be closed. For details on how pull requests are processed, please see below. Feature requests may be labeled with `volunteer_needed` if none of the LAMMPS developers has the time and the required knowledge implement the feature. -For bug reports, the next step is that one of the core LAMMPS developers will self-assign to the issue and try to confirm the bug. If confirmed, the `bug` label and potentially other labels are added to classify the issue and its impact to LAMMPS. Before confirming, further questions may be asked or requests for providing additional input files or details about the steps required to reproduce the issue. Any bugfix is likely to be submitted as a pull request (more about that below) and since most bugs require only local changes, the bugfix may be included in a pull request specifically set up to collect such local bugfixes or small enhancements. Once the bugfix is included in the master branch, the issue will be closed. +For bug reports, the next step is that one of the core LAMMPS developers will self-assign to the issue and try to confirm the bug. If confirmed, the `bug` label and potentially other labels are added to classify the issue and its impact to LAMMPS. Otherwise the `unconfirmed` label will be applied and some comment about what was tried to confirm the bug added. Before confirming, further questions may be asked or requests for providing additional input files or details about the steps required to reproduce the issue. Any bugfix will be submitted as a pull request (more about that below) and since most bugs require only local changes, the bugfix may be included in a pull request specifically set up to collect such local bugfixes or small enhancements. Once the bugfix is included in the master branch, the issue will be closed. ### Pull Requests -For submitting pull requests, there is a [detailed tutorial](https://lammps.sandia.gov/doc/Howto_github.html) in the LAMMPS manual. Thus only a brief breakdown of the steps is presented here. Please note, that the LAMMPS developers are still reviewing and trying to improve the process. If you are unsure about something, do not hesitate to post a question on the lammps-users mailing list or contact one fo the core LAMMPS developers. -Immediately after the submission, the LAMMPS continuing integration server at ci.lammps.org will download your submitted branch and perform a simple compilation test, i.e. will test whether your submitted code can be compiled under various conditions. It will also do a check on whether your included documentation translates cleanly. Whether these tests are successful or fail will be recorded. If a test fails, please inspect the corresponding output on the CI server and take the necessary steps, if needed, so that the code can compile cleanly again. The test will be re-run each the pull request is updated with a push to the remote branch on GitHub. -Next a LAMMPS core developer will self-assign and do an overall technical assessment of the submission. If you are not yet registered as a LAMMPS collaborator, you will receive an invitation for that. As part of the assessment, the pull request will be categorized with labels. There are two special labels: `needs_work` (indicates that work from the submitter of the pull request is needed) and `work_in_progress` (indicates, that the assigned LAMMPS developer will make changes, if not done by the contributor who made the submit). +Pull requests are the **only** way that changes get made to the LAMMPS distribution. So also the LAMMPS core developers will submit pull requests for their own changes and discuss them on GitHub. Thus if you submit a pull request it will be treated in a similar fashion. When you submit a pull request you may opt to submit a "Draft" pull request. That means your changes are visible and will be subject to testing, but reviewers will not be (auto-)assigned and comments will take into account that this is not complete. On the other hand, this is a perfect way to ask the LAMMPS developers for comments on non-obvious changes and get feedback and possible suggestions for improvements or recommendations about what to avoid. +Immediately after the submission, the LAMMPS continuing integration server at ci.lammps.org will download your submitted branch and perform a number of tests: it will tests whether it compiles cleanly under various conditions, it will also do a check on whether your included documentation translates cleanly and run some unit tests and other checks. Whether these tests are successful or fail will be recorded. If a test fails, please inspect the corresponding output on the CI server and take the necessary steps, if needed, so that the code can compile cleanly again. The test will be re-run each time the pull request is updated with a push to the remote branch on GitHub. If you are unsure about what you need to change, ask a question in the discussion area of the pull request. +Next a LAMMPS core developer will self-assign and do an overall technical assessment of the submission. If you submitted a draft pull request, this will not happen unless you mark it "ready for review". If you are not yet invited as a LAMMPS collaborator, and your contribution seems significant, you may also receive an invitation for collaboration on the LAMMPS repository. As part of the assessment, the pull request will be categorized with labels. There are two special labels: `needs_work` (indicates that work from the submitter of the pull request is needed) and `work_in_progress` (indicates, that the assigned LAMMPS developer will make changes, if not done by the contributor who made the submit). You may also receive comments and suggestions on the overall submission or specific details and on occasion specific requests for changes as part of the review. If permitted, also additional changes may be pushed into your pull request branch or a pull request may be filed in your LAMMPS fork on GitHub to include those changes. The LAMMPS developer may then decide to assign the pull request to another developer (e.g. when that developer is more knowledgeable about the submitted feature or enhancement or has written the modified code). It may also happen, that additional developers are requested to provide a review and approve the changes. For submissions, that may change the general behavior of LAMMPS, or where a possibility of unwanted side effects exists, additional tests may be requested by the assigned developer. -If the assigned developer is satisfied and considers the submission ready for inclusion into LAMMPS, the pull request will receive approvals and be merged into the master branch by one of the core LAMMPS developers. After the pull request is merged, you may delete the feature branch used for the pull request in your personal LAMMPS fork. -Since the learning curve for git is quite steep for efficiently managing remote repositories, local and remote branches, pull requests and more, do not hesitate to ask questions, if you are not sure about how to do certain steps that are asked of you. Even if the changes asked of you do not make sense to you, they may be important for the LAMMPS developers. Please also note, that these all are guidelines and nothing set in stone. So depending on the nature of the contribution, the workflow may be adjusted. +If the assigned developer is satisfied and considers the submission ready for inclusion into LAMMPS, the pull request will receive approvals and be merged into the master branch by one of the core LAMMPS developers. After the pull request is merged, you may delete the feature branch used for the pull request in your personal LAMMPS fork. The minimum requirement to merge a pull request is that all automated tests have to pass and at least one LAMMPS developer has approved integrating the submitted code. Since the approver will not be the person merging a pull request, you will have at least two LAMMPS developers that looked at your contribution. +Since the learning curve for git is quite steep for efficiently managing remote repositories, local and remote branches, pull requests and more, do not hesitate to ask questions, if you are not sure about how to do certain steps that are asked of you. Even if the changes asked of you do not make sense to you, they may be important for the LAMMPS developers. Please also note, that these all are guidelines and nothing set in stone. So depending on the nature of the contribution, the work flow may be adjusted. diff --git a/doc/github-development-workflow.md b/doc/github-development-workflow.md index c34a67dfcf..c0e35daf3f 100644 --- a/doc/github-development-workflow.md +++ b/doc/github-development-workflow.md @@ -6,7 +6,7 @@ choices the LAMMPS developers have agreed on. Git and GitHub provide the tools, but do not set policies, so it is up to the developers to come to an agreement as to how to define and interpret policies. This document is likely to change as our experiences and needs change and we try to -adapt accordingly. Last change 2018-12-19. +adapt accordingly. Last change 2021-09-02. ## Table of Contents @@ -23,10 +23,10 @@ adapt accordingly. Last change 2018-12-19. In the interest of consistency, ONLY ONE of the core LAMMPS developers should doing the merging itself. This is currently -[@akohlmey](https://github.com/akohlmey) (Axel Kohlmeyer). -If this assignment needs to be changed, it shall be done right after a -stable release. If the currently assigned developer cannot merge outstanding pull -requests in a timely manner, or in other extenuating circumstances, +[@akohlmey](https://github.com/akohlmey) (Axel Kohlmeyer). If this +assignment needs to be changed, it shall be done right after a stable +release. If the currently assigned developer cannot merge outstanding +pull requests in a timely manner, or in other extenuating circumstances, other core LAMMPS developers with merge rights can merge pull requests, when necessary. @@ -55,13 +55,14 @@ the required changes or ask the submitter of the pull request to implement them. Even though, all LAMMPS developers may have write access to pull requests (if enabled by the submitter, which is the default), only the submitter or the assignee of a pull request may do so. During this -period the `work_in_progress` label shall be applied to the pull +period the `work_in_progress` label may be applied to the pull request. The assignee gets to decide what happens to the pull request next, e.g. whether it should be assigned to a different developer for additional checks and changes, or is recommended to be merged. Removing the `work_in_progress` label and assigning the pull request to the developer tasked with merging signals that a pull request is ready to be -merged. +merged. In addition, a `ready_for_merge` label may also be assigned +to signal urgency to merge this pull request quickly. ### Pull Request Reviews @@ -97,108 +98,50 @@ rationale behind choices made. Exceptions to this policy are technical discussions, that are centered on tools or policies themselves (git, GitHub, c++) rather than on the content of the pull request. -### Checklist for Pull Requests - -Here are some items to check: - * source and text files should not have CR/LF line endings (use dos2unix to remove) - * every new command or style should have documentation. The names of - source files (c++ and manual) should follow the name of the style. - (example: `src/fix_nve.cpp`, `src/fix_nve.h` for `fix nve` command, - implementing the class `FixNVE`, documented in `doc/src/fix_nve.rst`) - * all new style names should be lower case, the must be no dashes, - blanks, or underscores separating words, only forward slashes. - * new style docs should be added to the "overview" files in - `doc/src/Commands_*.rst`, `doc/src/{fixes,computes,pairs,bonds,...}.rst` - * check whether manual cleanly translates with `make html` and `make pdf` - * if documentation is (still) provided as a .txt file, convert to .rst - and remove the .txt file. For files in doc/txt the conversion is automatic. - * remove all .txt files in `doc/txt` that are out of sync with their .rst counterparts in `doc/src` - * check spelling of manual with `make spelling` in doc folder - * check style tables and command lists with `make style_check` - * new source files in packages should be added to `src/.gitignore` - * removed or renamed files in packages should be added to `src/Purge.list` - * C++ source files should use C++ style include files for accessing - C-library APIs, e.g. `#include ` instead of `#include `. - And they should use angular brackets instead of double quotes. Full list: - * assert.h -> cassert - * ctype.h -> cctype - * errno.h -> cerrno - * float.h -> cfloat - * limits.h -> climits - * math.h -> cmath - * complex.h -> complex - * setjmp.h -> csetjmp - * signal.h -> csignal - * stddef.h -> cstddef - * stdint.h -> cstdint - * stdio.h -> cstdio - * stdlib.h -> cstdlib - * string.h -> cstring - * time.h -> ctime - * Do NOT replace (as they are C++-11): `inttypes.h` and `stdint.h`. - * Code must follow the C++-11 standard. C++98-only is no longer accepted - * Code should use `nullptr` instead of `NULL` where applicable. - in individual special purpose packages - * indentation is 2 spaces per level - * there should be NO tabs and no trailing whitespace (review the "checkstyle" test on pull requests) - * header files, especially of new styles, should not include any - other headers, except the header with the base class or cstdio. - Forward declarations should be used instead when possible. - * iostreams should be avoided. LAMMPS uses stdio from the C-library. - * use of STL in headers and class definitions should be avoided. - exception is , but it won't need to be explicitly included - since pointers.h already includes it. so std::string can be used directly. - * there MUST NOT be any "using namespace XXX;" statements in headers. - * static class members should be avoided at all cost. - * anything storing atom IDs should be using `tagint` and not `int`. - This can be flagged by the compiler only for pointers and only when - compiling LAMMPS with `-DLAMMPS_BIGBIG`. - * when including both `lmptype.h` (and using defines or macros from it) - and `mpi.h`, `lmptype.h` must be included first. - * see https://github.com/lammps/lammps/blob/master/doc/include-file-conventions.md - for general include file conventions and best practices - * when pair styles are added, check if settings for flags like - `single_enable`, `writedata`, `reinitflag`, `manybody_flag` - and others are correctly set and supported. - ## GitHub Issues The GitHub issue tracker is the location where the LAMMPS developers and other contributors or LAMMPS users can report issues or bugs with -the LAMMPS code or request new features to be added. Feature requests -are usually indicated by a `[Feature Request]` marker in the subject. -Issues are assigned to a person, if this person is working on this -feature or working to resolve an issue. Issues that have nobody working -on them at the moment, have the label `volunteer needed` attached. +the LAMMPS code or request new features to be added. Bug reports have +a `[Bug]` marker in the subject line; suggestions for changes or +adding new functionality are indicated by a `[Feature Request]` +marker in the subject. This is automatically done when using the +corresponding template for submitting an issue. Issues may be assigned +to one or more developers, if they are working on this feature or +working to resolve an issue. Issues that have nobody working +on them at the moment or in the near future, have the label +`volunteer needed` attached. When an issue, say `#125` is resolved by a specific pull request, the comment for the pull request shall contain the text `closes #125` or `fixes #125`, so that the issue is automatically deleted when -the pull request is merged. +the pull request is merged. The template for pull requests includes +a header where connections between pull requests and issues can be listed +and thus were this comment should be placed. ## Milestones and Release Planning LAMMPS uses a continuous release development model with incremental changes, i.e. significant effort is made - including automated pre-merge -testing - that the code in the branch "master" does not get broken. -More extensive testing (including regression testing) is performed after -code is merged to the "master" branch. There are patch releases of -LAMMPS every 1-3 weeks at a point, when the LAMMPS developers feel, that -a sufficient amount of changes have happened, and the post-merge testing -has been successful. These patch releases are marked with a -`patch_` tag and the "unstable" branch follows only these -versions (and thus is always supposed to be of production quality, -unlike "master", which may be temporary broken, in the case of larger -change sets or unexpected incompatibilities or side effects. +testing - that the code in the branch "master" does not get easily +broken. These tests are run after every update to a pull request. More +extensive and time consuming tests (including regression testing) are +performed after code is merged to the "master" branch. There are patch +releases of LAMMPS every 3-5 weeks at a point, when the LAMMPS +developers feel, that a sufficient amount of changes have happened, and +the post-merge testing has been successful. These patch releases are +marked with a `patch_` tag and the "unstable" branch +follows only these versions (and thus is always supposed to be of +production quality, unlike "master", which may be temporary broken, in +the case of larger change sets or unexpected incompatibilities or side +effects. -About 3-4 times each year, there are going to be "stable" releases -of LAMMPS. These have seen additional, manual testing and review of +About 1-2 times each year, there are going to be "stable" releases of +LAMMPS. These have seen additional, manual testing and review of results from testing with instrumented code and static code analysis. -Also, in the last 2-3 patch releases before a stable release are -"release candidate" versions which only contain bugfixes and -documentation updates. For release planning and the information of -code contributors, issues and pull requests being actively worked on -are assigned a "milestone", which corresponds to the next stable -release or the stable release after that, with a tentative release -date. - +Also, the last 1-3 patch releases before a stable release are "release +candidate" versions which only contain bugfixes and documentation +updates. For release planning and the information of code contributors, +issues and pull requests being actively worked on are assigned a +"milestone", which corresponds to the next stable release or the stable +release after that, with a tentative release date. diff --git a/doc/include-file-conventions.md b/doc/include-file-conventions.md deleted file mode 100644 index 454964f0a9..0000000000 --- a/doc/include-file-conventions.md +++ /dev/null @@ -1,128 +0,0 @@ -# Outline of include file conventions in LAMMPS - -This purpose of this document is to provide a point of reference -for LAMMPS developers and contributors as to what include files -and definitions to put where into LAMMPS source. -Last change 2020-08-31 - -## Table of Contents - - * [Motivation](#motivation) - * [Rules](#rules) - * [Tools](#tools) - * [Legacy Code](#legacy-code) - -## Motivation - -The conventions outlined in this document are supposed to help make -maintenance of the LAMMPS software easier. By trying to achieve -consistency across files contributed by different developers, it will -become easier for the code maintainers to modify and adjust files and, -overall, the chance for errors or portability issues will be reduced. -The rules employed are supposed to minimize naming conflicts and -simplify dependencies between files and thus speed up compilation. They -may, as well, make otherwise hidden dependencies visible. - -## Rules - -Below are the various rules that are applied. Not all are enforced -strictly and automatically. If there are no significant side effects, -exceptions may be possible for cases where a full compliance to the -rules may require a large effort compared to the benefit. - -### Core Files Versus Package Files - -All rules listed below are most strictly observed for core LAMMPS files, -which are the files that are not part of a package, and the files of the -packages MOLECULE, MANYBODY, KSPACE, and RIGID. On the other end of -the spectrum are USER packages and legacy packages that predate these -rules and thus may not be fully compliant. Also, new contributions -will be checked more closely, while existing code will be incrementally -adapted to the rules as time and required effort permits. - -### System Versus Local Header Files - -All system- or library-provided include files are included with angular -brackets (examples: `#include ` or `#include `) while -include files provided with LAMMPS are included with double quotes -(examples: `#include "pointers.h"` or `#include "compute_temp.h"`). - -For headers declaring functions of the C-library, the corresponding -C++ versions should be included (examples: `#include ` or -`#include ` instead of `#include ` or -`#include` ). - -### C++ Standard Compliance - -LAMMPS core files use standard conforming C++ compatible with the -C++11 standard, unless explicitly noted. Also, LAMMPS uses the C-style -stdio library for I/O instead of iostreams. Since using both at the -same time can cause problems, iostreams should be avoided where possible. - -### Lean Header Files - -Header files will typically contain the definition of a (single) class. -These header files should have as few include statements as possible. -This is particularly important for classes that implement a "style" and -thus use a macro of the kind `SomeStyle(some/name,SomeName)`. These will -all be included in the auto-generated `"some_style.h"` files which -results in a high potential for direct or indirect symbol name clashes. - -In the ideal case, the header would only include one file defining the -parent class. That would typically be either `#include "pointers.h"` for -the `Pointers` class, or a header of a class derived from it like -`#include "pair.h"` for the `Pair` class and so on. References to other -classes inside the class should be make through pointers, for which forward -declarations (inside the `LAMMPS_NS` or the new class' namespace) can -be employed. The full definition will then be included into the corresponding -implementation file. In the given example from above, the header file -would be called `some_name.h` and the implementation `some_name.cpp` (all -lower case with underscores, while the class itself would be in camel case -and no underscores `SomeName`, and the style name with lower case names separated by -a forward slash). - -### Implementation Files - -In the implementation files (typically, those would have the same base name -as the corresponding header with a .cpp extension instead of .h) include -statements should follow the "include what you use" principle. - -### Order of Include Statements - -Include files should be included in this order: -* the header matching the implementation (`some_class.h` for file `some_class.cpp`) -* mpi.h (only if needed) -* LAMMPS local headers (preferably in alphabetical order) -* system and library headers (anything that is using angular brackets; preferably in alphabetical order) -* conditional include statements (i.e. anything bracketed with ifdefs) - -### Special Cases and Exceptions - -#### pointers.h - -The `pointer.h` header file also includes (in this order) `lmptype.h`, -`mpi.h`, `cstddef`, `cstdio`, `string`, `utils.h`, and `fmt/format.h` -and through `lmptype.h` indirectly also `climits`, `cstdlib`, `cinttypes`. -This means any header including `pointers.h` can assume that `FILE`, -`NULL`, `INT_MAX` are defined, and the may freely use the std::string -for arguments. Corresponding implementation files do not need to include -those headers. - -## Tools - -The [Include What You Use tool](https://include-what-you-use.org/) -can be used to provide supporting information about compliance with -the rules listed here. Through setting `-DENABLE_IWYU=on` when running -CMake, a custom build target is added that will enable recording -the compilation commands and then run the `iwyu_tool` using the -recorded compilation commands information when typing `make iwyu`. - -## Legacy Code - -A lot of code predates the application of the rules in this document -and the rules themselves are a moving target. So there are going to be -significant chunks of code that do not fully comply. This applies -for example to the REAXFF, or the ATC package. The LAMMPS -developers are dedicated to make an effort to improve the compliance -and welcome volunteers wanting to help with the process. - diff --git a/doc/lammps.1 b/doc/lammps.1 index b7431319ba..40d4295b7e 100644 --- a/doc/lammps.1 +++ b/doc/lammps.1 @@ -54,7 +54,7 @@ using this parameter can be chosen arbitrarily at configuration time, but more common is to just use .B lmp -without a suffix. In this manpage we will use +without a suffix. In this man page we will use .B lmp to represent any of those names. @@ -94,7 +94,7 @@ Enable or disable general KOKKOS support, as provided by the KOKKOS package. Even if LAMMPS is built with this package, this switch must be set to \fBon\fR to enable running with KOKKOS-enabled styles. More details on this switch and its optional keyword value pairs are discussed -at: https://lammps.sandia.gov/doc/Run_options.html +at: https://docs.lammps.org/Run_options.html .TP \fB\-l \fR or \fB\-log \fR Specify a log file for LAMMPS to write status information to. @@ -122,6 +122,38 @@ to perform client/server messaging with another application. .B LAMMPS can act as either a client or server (or both). .TP +\fB\-mdi ''\fR +This flag is only recognized and used when +.B LAMMPS +has support for the MolSSI +Driver Interface (MDI) included as part of the MDI package. This flag is +specific to the MDI library and controls how +.B LAMMPS +interacts with MDI. There are usually multiple flags that have to follow it +and those have to be placed in quotation marks. For more information about +how to launch LAMMPS in MDI client/server mode please refer to the +MDI How-to at https://docs.lammps.org/Howto_mdi.html +.TP +\fB\-c\fR or \fB\-cite