diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 721e311cdc19bab8e4dd21fada03ed81f2ccd58b..467a6f8170d65e854ec68ac8204060c9f40d7245 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,32 +1,35 @@ -# How to contribute -You can contribute to this project in many ways: +# How to contribute +You can contribute to this project in many ways: -* [contributing new features or improving existing ones;](#development) -* [subscribing and partecipating to the users mailing list;](https://lists.quantum-espresso.org/mailman/listinfo/users) +* [contributing new features or improving existing ones;](#development) +* [subscribing and partecipating to the users mailing list;](https://lists.quantum-espresso.org/mailman/listinfo/users) * [reporting bugs and proposing changes in the Issue section of the gitlab repository;](#creating-issues) * [preparing new tests for the test suite](#adding tests) -## Development +## Development If you want to contribute serious and non-trivial stuff ( or even simple and trivial stuff ) you just have to *fork* this repository; keep it updated; -when your contribution is ready, submit a merge request to the development branch of this repository. -After some basic tests ran by gitlab CI and approval your changes will be merged in develop. -When the whole test-suite has been tested your contribution will be merged to the master branch. - -A basic guide on how to work with `git` can be found [here](https://docs.gitlab.com/ce/gitlab-basics/README.html). A more thorough introduction to `git` is provided by [proGit](https://git-scm.com/book/en/v2) online e-book +when your contribution is ready, submit a merge request to the development branch of this repository. +After some basic tests ran by gitlab CI and approval your changes will be merged in develop. +When the whole test-suite has been tested your contribution will be merged to the master branch. -#### Proposed workflow +A basic guide on how to work with `git` can be found [here](https://docs.gitlab.com/ce/gitlab-basics/README.html). A more thorough introduction to `git` is provided by [proGit](https://git-scm.com/book/en/v2) online e-book - - register on [gitlab](https://gitlab.com/users/sign_in); + + +#### Proposed workflow + + - register on [gitlab](https://gitlab.com/users/sign_in); - [fork the QEF/q-e project](https://docs.gitlab.com/ce/gitlab-basics/fork-project.html); - [create a local copy of __your__ repository on your workstation(s)](https://docs.gitlab.com/ce/gitlab-basics/command-line-commands.html#clone-your-project); - - [once your contribution is ready push it into __your__ repository](https://docs.gitlab.com/ce/gitlab-basics/start-using-git.html#send-changes-to-gitlab-com); + - [once your contribution is ready push it into __your__ repository](https://docs.gitlab.com/ce/gitlab-basics/start-using-git.html#send-changes-to-gitlab-com); - [create a merge request to the `develop` branch of QEF/q-e](https://docs.gitlab.com/ce/gitlab-basics/add-merge-request.html#how-to-create-a-merge-request) - - +## Development tools +[Here](dev-tools/) you can find several tools that will assist you while contributing to the QE source code. + ## Creating Issues -You can report bugs and propose new developments posting on the [issue]( https://gitlab.com/QEF/q-e/issues) -section of this repository. Partecipation to the issue discussions are also a welcome contribution. -When reporting bugs try to help other partecipant to reproduce the problem by providing input and output files. +You can report bugs and propose new developments posting on the [issue]( https://gitlab.com/QEF/q-e/issues) +section of this repository. Partecipation to the issue discussions are also a welcome contribution. +When reporting bugs try to help other partecipant to reproduce the problem by providing input and output files. diff --git a/README.md b/README.md index eeeb3c4ac5fb37e3751501520c69ee3a6de13a8f..637847ea5ce25320e1052932cf27866c4b56a664 100644 --- a/README.md +++ b/README.md @@ -33,11 +33,15 @@ http://www.quantum-espresso.org/ ## Modular libraries The following libraries have been isolated and partially encapsulated in view of their release for usage in other codes as well: -- UtilXlib performing basic MPI handling, error handling, timing handling. -- FFTXlib parallel (MPI and OpenMP) distributed three-dimensional FFTs, performing also load-balanceddistribution of data (plane waves, G-vectors and real-space grids) across processors. -- LAXlib parallel distributed dense-matrix diagonalization, using ELPA, SCALapack, or a custom algorithm. -- KS Solver parallel iterative diagonalization for the Kohn-Sham Hamiltonian (represented as an operator),using block Davidson and band-by-band Conjugate-Gradient algorithms. -- LRlib performs a variety of tasks connected with (time-dependent) DFPT, to be used also in connectionwith Many-Body Perturbation Theory. +- UtilXlib: performing basic MPI handling, error handling, timing handling. +- FFTXlib: parallel (MPI and OpenMP) distributed three-dimensional FFTs, performing also load-balanced distribution of data (plane waves, G-vectors and real-space grids) across processors. +- LAXlib: parallel distributed dense-matrix diagonalization, using ELPA, SCALapack, or a custom algorithm. +- KS Solver: parallel iterative diagonalization for the Kohn-Sham Hamiltonian (represented as an operator),using block Davidson and band-by-band Conjugate-Gradient algorithms. +- LRlib: performs a variety of tasks connected with (time-dependent) DFPT, to be used also in connection with Many-Body Perturbation Theory. + +## Contributing +Before contributing please read the [Contribution Guidelines](CONTRIBUTING.MD) + ## LICENSE diff --git a/dev-tools/README.md b/dev-tools/README.md index 4490891a80a945a12c32e24169f50dcc05bee549..e8aa1665c27de3666a261a3b724e65d4ed39a325 100644 --- a/dev-tools/README.md +++ b/dev-tools/README.md @@ -1,29 +1,41 @@ +# Dev Tools + This directory contains several tools that may be useful for developers - `mem_counter`. A script that tracks all calls to `allocate` and `deallocate`, appending a call to subroutine `UtilXlib/mem_counter.f90`. Calls python script `mem_counter.py`, written by Pietro BonfĂ (CINECA). `mem_counter -h` gives information on how to use it. -- `src-normal`. A script that "normalizes" the fortran syntax to QE style. +- `src-normal`. A script that "normalizes" the fortran syntax to [QE style](#style). Calls python script `src-normal.py`, written by Norbert Nemec. + Usage: `src-normal file1.f90 [file2.f90 ...]` or `src-normal` + - `calltree.pl` A perl script, to be run from the root QE directory, producing in the - standard output the tree of called routines + standard output the tree of called routines - `callhtml.pl` - As above, producing a html page with the tree of called routines + As above, producing a html page with the tree of called routines - `release.sh` Script for packaging releases - obsolete, to be adapted to git -- utilities for PWgui: +- Utilities for PWgui: * `check_gui` (called via `Makefile`) * `diff_gui_help` * `guihelp.xsl` * `update_gui_help` -- utilities for helpdoc (see `README.helpdoc`): +- Utilities for helpdoc (see `README.helpdoc`): * `helpdoc` * `helpdoc.d` * `helpdoc.schema` * `input_xx.xsl` -- utilities for emacs_mode: +- Utilities for emacs_mode: * `gen-emacs-mode` * `gen-emacs-mode.tcl` + +## Coding style +This are some basic rules to follow when writting Fortran code. +* Use spaces for indentation instead of tabs (tab width 8 characters). +* Trailing whitespaces at the end the line should be removed. +* Normalize multiword keywords. +* Use capitalize version of the intrisic keywords (IF, DO, SUBROUTINE, etc.). +* Perefer the newest version of the relational (==, >, etc.) instead of the old one (.eq., .gt., etc.) diff --git a/dev-tools/src-normal.py b/dev-tools/src-normal.py index baf8ce084d79eee2281857553c3e54c72220e6fd..7d432878c50c27fa27f89f56697569e1f808d1c4 100755 --- a/dev-tools/src-normal.py +++ b/dev-tools/src-normal.py @@ -5,7 +5,7 @@ # USAGE: src-normal.py < input.f90 > output.f90 # # Script to normalize Fortran source code: -# a) expand tabs to spaces (tab width 8 characters +# a) expand tabs to spaces (tab width 8 characters) # b) remove trailing space # c) normalize multiword keywords # d) normalize capitalization of keywords and intrinsics