mirror of https://gitlab.com/QEF/q-e.git
First set of updates to the developer's manual
git-svn-id: http://qeforge.qe-forge.org/svn/q-e/trunk/espresso@12309 c92efa57-630b-4861-b058-cf58834340f0
This commit is contained in:
parent
a528fc89f3
commit
28bb0dbebc
|
@ -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:
|
||||
|
|
Loading…
Reference in New Issue