diff --git a/Doc/developer_man.tex b/Doc/developer_man.tex index 6bad13f5a..fab512189 100644 --- a/Doc/developer_man.tex +++ b/Doc/developer_man.tex @@ -1,5 +1,5 @@ \documentclass[12pt,a4paper]{article} -\def\version{5.3} +\def\version{5.4} \def\qe{{\sc Quantum ESPRESSO}} \def\qeforge{\texttt{qe-forge.org}} \textwidth = 17cm @@ -75,15 +75,16 @@ You can contribute to a better \qe, even as an ordinary user, by: for reporting bugs". \item Improving the documentation (generic complaints or suggestions that "there should be this and that" do not qualify as improvements). -\item Suggesting changes: note however that suggestions requiring a - significant amount of work are welcome only if accompanied by +\item Suggesting changes: contact developers at + \texttt{q-e-developers[.at.]qe-forge[.dot.]org} mailing list, + Unless there are technical reasons not to follow your suggestion, + we will try to make you happy. Note however that suggestions requiring + a significant amount of work are welcome only if accompanied by implementation or by a promise of future implementation (fulfilled promises are strongly preferred to forgotten ones). -\item Adding new features to the code. If you like to have something - added to \qe, contact the developers via the - \texttt{q-e-developers[.at.]qe-forge[.dot.]org} mailing list. - Unless there are technical reasons not to include your changes, we - will try to make you happy (no warranty that we will actually succeed). +\item Adding new features to the code: see Sect.\ref{SubSec:BeDev}, + "How to become a developer", in particular Sect.\ref{SubSec:Contrib}, + "Contributing new developments". \end{itemize} \newpage @@ -106,8 +107,8 @@ molecular dynamics on the ground state; \end{itemize} \end{itemize} Note that some libraries are downloaded on demand from the web -during the installation of the core distribution. Then comes a first -outer shell of {\em additional} packages, that can be downloaded and +during the installation of the core distribution. Then comes a +shell of {\em additional} packages, that can be downloaded and installed from the core distribution using \texttt{make}: \begin{itemize} \item \texttt{atomic}: pseudopotential generation @@ -116,43 +117,42 @@ installed from the core distribution using \texttt{make}: \item \texttt{PWCOND}: ballistic conductance \item \texttt{XSPECTRA}: calculation of X-Ray spectra \item \texttt{TDDFPT}: Time-dependent DFPT -\end{itemize} -All these packages use routines from the core distribution. - -A second shell of additional packages, also downloaded and installed -on demand from the core distribution, includes -\begin{itemize} +\item \texttt{EPW}: electron-phonon \item \texttt{GIPAW}: calculation of NMR coefficients and chemical shifts, -\item \texttt{EPW}: electron-phonon (under development, -requires \texttt{PHonon}). -\end{itemize} -The only difference between the ''first'' and ''second'' shell is that -the latter are stored in separate SVN repositories. - -In a third shell of additional packages we find -\begin{itemize} \item \texttt{GWL}: GW calculations using Lanczos chains. \end{itemize} -This also uses routines from \qe, but it must be separately -downloaded and installed. +All these packages use routines from the core distribution. Note that +\begin{itemize} +\item \texttt{EPW} and \texttt{GWL} require \texttt{PHonon}; +\item \texttt{GWL} must be separately downloaded; +\item \texttt{GIPAW} is stored in a separate SVN repository. +\end{itemize} There is then a shell of {\em external} packages, which typically read data produced by \qe\ but do not need it to work. Some of them -(notably Yambo and WanT) can be automatically downloaded and installed -from the core distribution using \texttt{make}. +(notably Yambo, Wannier90, WanT) can be automatically downloaded and +installed from the core distribution using \texttt{make}. Finally there are {\em plugins}: these modify \qe\ packages, adding -new functionalities. The only plugin currently released is Plumed -(metadynamics), but other may come soon. +new functionalities. Currently the following plugins are available: +\begin{itemize} +\item \texttt{Plumed}, v.1.3 only, for metadynamics; +\item \texttt{Environ}, for calculations with a solvent. +\end{itemize} \section{How to become a developer} +\label{SubSec:BeDev} If you want to get involved as a developer and contribute serious or nontrivial stuff (or even simple and trivial stuff), you should -first of all register on \qeforge\ as a developer for the \qe\ -project. +first of all register on \qeforge, following the instructions. \subsection{About \qeforge} +\label{SubSec:qeforge} + +{\em Important notice: \qeforge\ will be upgraded in the next months +with new hardware and software. Some of the following pieces of +information may become obsolete.} \qeforge\ is the portal for \qe\ developers, contributors, and for anybody else wanting to develop a project in the @@ -169,13 +169,16 @@ you may open your own project, retaining all rights on it the "projects" page, click on the link "add new project", fill the form (note that the Unix name given to the project cannot be modified). You have the choice between a repository using -CVS, SVN, \texttt{git}, plus other choices. +CVS, SVN, \texttt{git}, others. Please avoid CVS +(obsolete), prefer \texttt{git} (it is easier to move the +repository). You may as well register as a developer in an existing project: go to the project page, click on button ''Request to become a developer'' under the ''Activity'' graph on the top of the column at the right, to obtain the permission -from the administrator of the project. +from the administrator of the project (please contact the +project administratior by mail!). You need to register your SSH keys in order to have read-write access the repository (if you have such permissions). Generate @@ -207,7 +210,7 @@ for communications among developers and people interested in the development of \qe. Only registered users can post but messages from unregistered users are monitored and approved if relevant. -\item \texttt{q-e-commits}(medium traffic): for automatic +\item \texttt{q-e-commits} (medium traffic): for automatic commit messages. Note that replies to commit messages go to the mailing list: in case of doubts or questions or remarks over a specific commit, feel free to reply. @@ -217,7 +220,7 @@ Everybody is encouraged to explore other capabilities of \qeforge. All \qe\ developer are {\em strongly} invited to subscribe to the two mailing lists \texttt{q-e-developers} and \texttt{q-e-commits}. -Those who don't lose i) the opportunity to follow what is going on, +Those who don't, lose i) the opportunity to follow what is going on, ii) the right to complain if something has gone into a direction they don't like. Note that subscription to mailing lists is not automatic when you register: you should subscribe using the links @@ -228,61 +231,91 @@ Please also consider subscribing to the bug tracker: select the bug is filed. \subsection{Contributing new developments} - -{\em Important notice: starting with release 5.3, there will be important -changes in the development model of \qe. Stay tuned.} +\label{SubSec:Contrib} Various procedures can be followed to contribute new developments. It is possible to contribute: \begin{itemize} -\item a small (or large) piece of code to an existing package; or +\item a small, or large, piece of code to an existing package; or \item a new package that uses \qe\ as a library; or \item a ``plugin'' that modifies \qe, adding a new functionality; or \item a new ``external'' package that just reads data file produced by QE. \end{itemize} -The ideal procedure depends upon the kind of project you have in -mind. In all cases, you should learn how to use SVN: see Sect.\ref{Sec:SVN}, -"Using SVN". The three typical cases are: +The ideal procedure depends upon the kind of project you have in mind. + +As a rule: if you plan to release your work in the public release, you +should always keep your work aligned to the current development version +of \qe. This is especially important if your project \begin{itemize} -\item[a)] If your project involves changes or additions affecting only -a small part of \qe, it is usually convenient to work directly on -the main SVN repository (the "trunk"). -\item[b)] -If your project involves major or extensive changes to the core of -\qe, it may be a good idea to make a SVN "branch" and work on it. -Note that your branch will necessarily be public, since the SVN -trunk is public. -\item[c)] -If your project involves a major new addition (e.g. a new package), -or if you do not want it to be public during its development, -it may be a good idea to register it as a new \qeforge\ project -with a separate SVN repository. It is possible to restrict access -to selected \qe\ developers; or to keep it private; or to have -two repositories, one public and one private. It is possible to -have the public repository automatically downloaded into the -SVN copy of \qe\ (see Sect.\ref{SubSec:propedit}). - +\item involves major or extensive or even small but critical or numerous + changes to existing \qe\ routines, +\item makes usage of existing (modified or unmodified) \qe\ routines. \end{itemize} +Modifying the latest stable version is not a good idea. Modifying +an {\em old} stable version is an {\em even worse idea}. New code +based on old versions will invariably be obsolete after a few months, +{\em very} obsolete after a few years. Experience shows that new projects +may take a long time before reaching a public release, and that the +major stumbling block is the alignment to the newer \qe\ distribution. -For case a), you should from time to time update your copy (using command -\texttt{svn update}), verify if changes made meanwhile by other developers +The sole exception is when your changes are either relatively small, or +localized to a small part of \qe, or they are quite independent anyway +from the rest of \qe. In that case, you can just send a patch or the +modified routine(s) to an expert developer who will review it and +take the appropriate steps. + +{\em Notice:} the development model of \qe\ has undergone +significant changes between releases 5.3 and 5.4. Since v.5.4, only +package maintainers and a few expert developers are allowed to commit +into the main ("trunk") SVN repository. Only ``safe'' changes can be +committed: the repository should always be at or close to production +status. SVN branches are discouraged: experience shows that too many +branches are never merged. + +Due to various \qeforge\ limitations, anonymous SVN access is also disabled. +People who need to access a development version may use the link to the +"Daily Snapshot" on the www.quantum-espresso.org web site. + +People who need to stay aligned to the development of \qe may use the official +\texttt{git} mirror, available on \qeforge\ under the project ``qe-private''. +Please apply for an acount on qe-forge if you haven't one +(see Sect.\ref{SubSec:qeforge} for details), contact support[.at.]qe-forge.org +and explain what you need and why. To check out the repository: +\begin{verbatim} + git clone ssh://username@qeforge.qe-forge.org/gitroot/q-e-private +\end{verbatim} +This repository is only for pull operation and it is one way repository, +meaning it is automatically aligned by a script with the SVN repository. +Committing into this repository does not produce a commit in the SVN. +So never commit ;-). See Sect.\ref{Sec:git}, ``Using git'', for more +instructions on how to use \texttt{git}. You should also +register to the q-e-commit@qe-forge.org mailing list in order to better +follow what is going on in the main repository. + +If your project involves a major new addition (e.g. a new package), +consider registering it as a new \qeforge\ project, with a separate +SVN or (better) \texttt{git} repository. It is possible to keep the +project private, or to restrict access to selected \qe\ developers. + +% or to have two repositories, one public and one private. +% It is also possible to have the public repository automatically +% downloaded into the SVN copy of \qe\ (see Sect.\ref{SubSec:propedit}). + +{\em Important:} keep your copy of the distribution aligned to the SVN. +Don't work for years, or even for months, without keeping an eye to +what is going on in the SVN. This is especially true for projects that +are ``tightly bound'' to \qe, that is, use \qe\ code and routines. +Frequently update your copy (using command \texttt{svn update} or +\texttt{git pull}), verify if changes made meanwhile by other developers conflict with your changes. Conflicts are in most cases easy to solve: -see Sect. \ref{SubSec:Conflicts} for hints on how to -remove conflicts and on how to figure out what went wrong. -Once you are happy with your modified version, you can commit your -changes, or ask one of the expert developers to do this if you do not -feel confident enough. +see Sect. \ref{SubSec:Conflicts} for hints on how to remove conflicts +and on how to figure out what went wrong. -For case b), you should from time to time align your branch with the -trunk. See Sect. \ref{SubSec:Merge} for hints on how to do this. - -For case c): if your project is ``loosely coupled'' to \qe, that is, -it just uses the \qe\ installation procedure and/or data files, there -shouldn't be any major problems, since major incompatible changes are -very rare (note however that the files produced by the phonon code -change more frequently). If your project is ``tightly bound'', i.e. -it uses routines from \qe, it is prudent to notify the other -developers. +If instead your project is ``loosely coupled'', that is, it just uses the +\qe\ installation procedure and/or data files, it is less likely to run +into problems, since major incompatible changes are quite rare. +You may still need to verify from time to time that everything keeps +working. though. \subsection{Hints, Caveats, Do's and Dont's for developers} @@ -293,7 +326,8 @@ page \texttt{www.quantum-espresso.org/road-map}, send a message to \texttt{q-e-developers}. \item Before starting writing code, inquire whether you can reuse code that is already available in the distribution. Avoid redundancy: -the only bug-free software line is the one that doesn't exist. +{\em the only bug-free software line is the one that doesn't exist} +(citation adapted from Henry Ford). \item When you make some changes: \begin{itemize} \item Check that are not spoiling other people's work. In particular, @@ -363,13 +397,14 @@ Typically, one should report the bug \end{itemize} The provided input should be simple and quick to execute. -\item If a bug is found in a stable (released) version of \qe, it must -be reported in the \texttt{Doc/release-notes} file. +\item If a bug is found in a stable (released) version of \qe, + he/she who fixes it must report it in the \texttt{Doc/release-notes} + file. \end{itemize} \section{Stable releases and development cycle} -Stable releases are labelled as $N.M.p$, where $N$=major, $M$=minor, -$p$=bugfix. The logic goes more or less as follows: +Stable releases (until v.5.4) are labelled as $N.M.p$, where $N$=major, +$M$=minor, $p$=bugfix. The logic goes more or less as follows: \begin{itemize} \item {\em Major}: when something really important changes, e.g. \begin{enumerate} @@ -389,7 +424,8 @@ It may be convenient to make a SVN branch at release $N.M.0$: this allows to go on with the development while keeping track of bug fixes. Since release 5.2 (June 20, 2015), stable release are packaged at -fixed dates. The initial schedule is a release every three months. +fixed dates. The initial schedule is a release every three to four months. +Since v.5.4 bugfix releases are no longer packaged. Releases are stored to \qeforge. Given the size of the complete distribution, the release is split into a ``core'' distribution and ``add-ons'', @@ -421,7 +457,7 @@ This manual and the user manual have to be updated. Edit the script \texttt{dev-tools/release.sh} to make tarballs. -\paragraph{Updating web site} After the release has been uploaded to +\paragraph{Updating web site} After the release is uploaded to \qeforge, the online documentation must be copied to directory \texttt{/var/www/quantum\_wp\_db/wordpress-3.1.4/wp-content/uploads/Doc} on the web site (this requires system privileges on the machine hosting @@ -2197,8 +2233,7 @@ The following web page may be useful: \subsection{Including a repository into the trunk} \label{SubSec:propedit} It is possible to download other repositories into the main \qe\ repository. -Currently, this possibility works only for GIPAW (and EPW, which -however is not aligned to the svn version); you need to be authorized +Currently, this possibility works only for GIPAW; you need to be authorized to access the GIPAW svn, though. From the trunk/ subdirectory (the one containing espresso/), type ``svn propedit svn:externals espresso''. An editor will open. Type the name of the subdirectory of ``espresso/'' @@ -2206,9 +2241,11 @@ where you want the repository to be downloaded, followed by the address of the repository, exit (not quit!) the editor. Example: \begin{verbatim} GIPAW http://qeforge.qe-forge.org/svn/qe-gipaw/trunk -EPW http://qeforge.qe-forge.org/svn/epw-public/trunk/EPW \end{verbatim} +\section{Using git} +\label{Sec:git} + \section{Bibliography} Fortran books: