diff --git a/AUTHORS.rst b/AUTHORS.rst index 5cae26d28..2cf60f05c 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -1,211 +1,207 @@ .. This file is part of Invenio. Copyright (C) 2015, 2017 CERN. Invenio is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. Invenio is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. In applying this license, CERN does not waive the privileges and immunities granted to it by virtue of its status as an Intergovernmental Organization or submit itself to any jurisdiction. - Authors ======= -You can contact us at <info@inveniosoftware.org>. +See :ref:`communication-channels` for how to get in touch with us. -Active contributors: - -* Alexander Wagner <alexander.wagner@desy.de> -* Annette Holtkamp <annette.holtkamp@cern.ch> -* Cornelia Plott <c.plott@fz-juelich.de> -* Cristian Bacchi <cristian.bacchi@gmail.com> -* Dan Michael O. Heggø <danmichaelo@gmail.com> -* Esteban J. G. Gabancho <esteban.jose.garcia.gabancho@cern.ch> -* Evelthon Prodromou <epro@prodromou.eu> -* Ferran Jorba <Ferran.Jorba@uab.cat> -* Flavio Costa <flavio.costa@cern.ch> -* Guillaume Lastecoueres <PX9e@gmx.fr> -* Harris Tzovanakis <me@drjova.com> -* Ivan Masár <helix84@centrum.sk> -* Jacopo Notarstefano <jacopo.notarstefano@cern.ch> -* Javier Martin <javier.martin.montull@cern.ch> -* Jiri Kuncar <jiri.kuncar@cern.ch> -* Jocelyne Jerdelet <jocelyne.jerdelet@cern.ch> -* Johnny Mariéthoz <johnny.mariethoz@rero.ch> -* Kenneth Hole <kenneth@tind.io> -* Kirsten Sachs <kirsten.sachs@desy.de> -* Lars Holm Nielsen <lars.holm.nielsen@cern.ch> -* Leonardo Rossi <leonardo.r@cern.ch> -* Ludmila Marian <ludmila.marian@gmail.com> -* Miguel Martín <miguelm@unizar.es> -* Nicolas Harraudeau <nicolas.harraudeau@cern.ch> -* Nikolaos Kasioumis <nikolaos.kasioumis@cern.ch> -* Øystein Blixhavn <oystein@blixhavn.no> -* Pamfilos Fokianos <pamfilos.fokianos@cern.ch> -* Petr Brož <petr.broz@heaven-industries.com> -* Roman Chyla <roman.chyla@cern.ch> -* Samuele Kaplun <samuele.kaplun@cern.ch> -* Sebastian Witowski <sebastian.witowski@cern.ch> -* Stefan Hesselbach <s.hesselbach@gsi.de> -* Theodoropoulos Theodoros <theod@lib.auth.gr> -* Tibor Simko <tibor.simko@cern.ch> -* Thorsten Schwander <thorsten.schwander@gmail.com> -* Wojciech Ziolek <wojciech.ziolek@cern.ch> - -Past contributors: +Active and past contributors: * Adrian Pawel Baran <adrian.pawel.baran@cern.ch> * Adrian-Tudor Panescu <adrian.tudor.panescu@cern.ch> * Alberto Pepe <alberto.pepe@cern.ch> * Alessio Deiana <alessio.deiana@cern.ch> +* Alexander Wagner <alexander.wagner@desy.de> * Alexandra Silva <xana@correio.ci.uminho.pt> * Alper Cinar <alper@srdc.com.tr> * Anna Afshar <anna.afsharghasemlouy@epfl.ch> +* Annette Holtkamp <annette.holtkamp@cern.ch> * Antonios Manaras <antonios.manaras@cern.ch> * Artem Tsikiridis <artem.tsikiridis@cern.ch> * Avraam Tsantekidis <avraam.tsantekidis@cern.ch> * Axel Voitier <axel.voitier@gmail.com> * Benoit Thiell <benoit.thiell@cern.ch> * Björn Oltmanns <bjoern.oltmanns@gmail.com> * Carmen Alvarez Perez <carmen.alvarez.perez@cern.ch> * Christopher Dickinson <christopher.dickinson@cern.ch> * Christopher Hayward <christopher.james.hayward@cern.ch> * Christopher Parker <chris.parker.za@gmail.com> +* Cornelia Plott <c.plott@fz-juelich.de> +* Cristian Bacchi <cristian.bacchi@gmail.com> +* Dan Michael O. Heggø <danmichaelo@gmail.com> * Daniel Lovasko <daniel.lovasko@cern.ch> * Daniel Stanculescu <daniel.stanculescu@cern.ch> * David Bengoa <david.bengoa.rocandio@cern.ch> * Diane Berkovits <diane.berkovits@cern.ch> * Dimitrios Semitsoglou-Tsiapos <dsemitso@cern.ch> * Dinos Kousidis <konstantinos.kousidis@cern.ch> * Eamonn Maguire <eamonnmag@gmail.com> +* Eduardo Benavidez <eduardo.benavidez@gmail.com> * Eduardo Margallo <eduardo.margallo@cern.ch> * Eirini Psallida <eirini.psallida@cern.ch> -* Erik Simon <erik.simon@unine.ch> * Eric Stahl <eric.stahl@utbm.fr> +* Erik Simon <erik.simon@unine.ch> +* Esteban J. G. Gabancho <esteban.jose.garcia.gabancho@cern.ch> +* Evelthon Prodromou <epro@prodromou.eu> * Fabio Souto <fsoutomoure@gmail.com> * Federico Poli <federico.poli@cern.ch> +* Ferran Jorba <Ferran.Jorba@uab.cat> +* Flavio Costa <flavio.costa@cern.ch> * Franck Grenier <franckgrenier@wanadoo.fr> * Frederic Gobry <frederic.gobry@epfl.ch> * Fredrik Nygård Carlsen <me@frecar.no> * Gabriel Hase <gabriel.hase@cern.ch> * Georgios Kokosioulis <giokokos@gmail.com> * Georgios Papoutsakis <georgios.papoutsakis@cern.ch> * Gerrit Rindermann <Gerrit.Rindermann@cern.ch> * giannistsan <tsanakts.10@gmail.com> * Gilles Louppe <g.louppe@gmail.com> * Giovanni Di Milia <gdimilia@cfa.harvard.edu> * Glenn Gard <glenng4@aol.com> * Graham R. Armstrong <graham.richard.armstrong@cern.ch> * Gregory Favre <gregory.favre@cern.ch> * Grzegorz Szpura <grzegorz.szpura@cern.ch> +* Guillaume Lastecoueres <PX9e@gmx.fr> * Guotie <guotie.9@gmail.com> -* Eduardo Benavidez <eduardo.benavidez@gmail.com> +* Harris Tzovanakis <me@drjova.com> * Hector Sanchez <hector.sanchez@cern.ch> * Henning Weiler <henning.weiler@cern.ch> * Ivan Masár <helix84@centrum.sk> +* Ivan Masár <helix84@centrum.sk> +* Jacopo Notarstefano <jacopo.notarstefano@cern.ch> * Jaime Garcia Llopis <jaime.garcia.llopis@cern.ch> * Jake Cowton <jake.calum.cowton@cern.ch> * Jan Aage Lavik <jan.age.lavik@cern.ch> * Jan Brice Krause <jan.brice.krause@cern.ch> * Jan Iwaszkiewicz <jan.iwaszkiewicz@cern.ch> * Jan Stypka <jan.stypka@cern.ch> +* Javier Martin <javier.martin.montull@cern.ch> * Jay Luker <lbjay@reallywow.com> * Jerome Caffaro <jerome.caffaro@cern.ch> +* Jiri Kuncar <jiri.kuncar@cern.ch> * João Batista <jnfbatista@gmail.com> * Joaquim Rodrigues Silvestre <joaquim.rodrigues.silvestre@cern.ch> +* Jocelyne Jerdelet <jocelyne.jerdelet@cern.ch> * Jochen Klein <klein.jochen@gmail.com> * Joe Blaylock <jrbl@slac.stanford.edu> * Joe MacMahon <joe.macmahon@cern.ch> * Joël Vogt <joel.vogt@unifr.ch> * Johann C. Rocholl <johann@browsershots.org> +* Johnny Mariéthoz <johnny.mariethoz@rero.ch> * Jorge Aranda Sumarroca <jorge.aranda.sumarroca@cern.ch> * Juan Francisco Pereira Corral <juan.francisco.pereira.corral@cern.ch> * Julio Pernia Aznar <jpernia@altransdb.com> * Juliusz Sompolski <julsomp@gmail.com> * Jurga Girdzijauskaite <jurga.gird@gmail.com> * Kamil Neczaj <kamil.neczaj@cern.ch> +* Kenneth Hole <kenneth@tind.io> * Kevin Bowrin <kjbowrin@gmail.com> * Kevin M. Flannery <flannery@fnal.gov> * Kevin Sanders <kevin.sanders@cern.ch> +* Kirsten Sachs <kirsten.sachs@desy.de> * Konstantinos Kostis <konstantinos.kostis@cern.ch> * Konstantinos Kousidis <dinossimpson@pb-d-128-141-29-229.cern.ch> * Konstantinos Ntemagkos <konstantinos.ntemagkos@cern.ch> * Krzysztof Jedrzejek <krzysztof.jedrzejek@cern.ch> * Krzysztof Lis <krzysztof.lis@cern.ch> * Kyriakos Liakopoulos <kyriakos.liakopoulos@cern.ch> -* Laura Rueda <laura.rueda@cern.ch> * Lars Christian Raae <lars.christian.raae@cern.ch> +* Lars Holm Nielsen <lars.holm.nielsen@cern.ch> +* Laura Rueda <laura.rueda@cern.ch> +* Leonardo Rossi <leonardo.r@cern.ch> * Lewis Barnes <lewis.barnes@cern.ch> +* Ludmila Marian <ludmila.marian@gmail.com> * Luke Andrew Smith <smithey_72@hotmail.com> * Maja Gracco <maja.gracco@cern.ch> * Marco Neumann <marco@crepererum.net> -* Marios Kogias <marioskogias@gmail.com> -* Markus Goetz <murxman@gmail.com> * Marcus Johansson <marcus.johansson@cern.ch> +* Marios Kogias <marioskogias@gmail.com> * Marko Niinimaki <manzikki@gmail.com> +* Markus Goetz <murxman@gmail.com> * Martin Vesely <martin.vesely@cern.ch> * Mateusz Susik <mateusz.susik@cern.ch> * Mathieu Barras <mbarras@gmail.com> +* Miguel Martín <miguelm@unizar.es> * Miguel Martinez Pedreira <miguel.martinez.pedreira@cern.ch> * Mikael Karlsson <i8myshoes@gmail.com> * Mikael Vik <mikael.vik@cern.ch> * Mike Marino <mmarino@gmail.com> * Mike Sullivan <sul@slac.stanford.edu> * Minn Soe <minn.soe@cern.ch> * Nicholas Robinson <nicholas.robinson@cern.ch> +* Nicolas Harraudeau <nicolas.harraudeau@cern.ch> * Nikola Yolov <nikola.yolov@cern.ch> * Nikolaos Kalodimas <nikolaos.kalodimas@cern.ch> +* Nikolaos Kasioumis <nikolaos.kasioumis@cern.ch> * Nikolay Dyankov <ndyankov@gmail.com> * Nino Jejelava <nino.jejelava@gmail.com> * Olivier Canévet <olivier.canevet@cern.ch> * Olivier Serres <olivier.serres@gmail.com> +* Øystein Blixhavn <oystein@blixhavn.no> * Øyvind Østlund <oyvind.ostlund@cern.ch> * Pablo Vázquez Caderno <pcaderno@cern.ch> +* Pamfilos Fokianos <pamfilos.fokianos@cern.ch> * Patrick Glauner <patrick.oliver.glauner@cern.ch> * Paulo Cabral <paulo.cabral@cern.ch> * Pedro Gaudencio <pmgaudencio@gmail.com> * Peter Halliday <phalliday@cornell.edu> +* Petr Brož <petr.broz@heaven-industries.com> * Petros Ioannidis <petros.ioannidis@cern.ch> * Piotr Praczyk <piotr.praczyk@piotr.praczyk@gmail.com> * Radoslav Ivanov <radoslav.ivanov@cern.ch> * Raja Sripada <raja.sripada@cern.ch> * Raquel Jimenez Encinar <raquel.jimenez.encinar@cern.ch> * Richard Owen <ro@tes.la> * Roberta Faggian <roberta.faggian@cern.ch> +* Roman Chyla <roman.chyla@cern.ch> * Ruben Pollan <ruben.pollan@cern.ch> * Sami Hiltunen <sami.mikael.hiltunen@cern.ch> * Samuele Carli <samuele.carli@cern.ch> +* Samuele Kaplun <samuele.kaplun@cern.ch> +* Sebastian Witowski <sebastian.witowski@cern.ch> * Stamen Todorov Peev <stamen.peev@cern.ch> +* Stefan Hesselbach <s.hesselbach@gsi.de> * Stephane Martin <stephane.martin@epfl.ch> +* Theodoropoulos Theodoros <theod@lib.auth.gr> * Thierry Thomas <thierry@FreeBSD.org> * Thomas Baron <thomas.baron@cern.ch> * Thomas Karampelas <thomas.karampelas@cern.ch> * Thomas McCauley <thomas.mccauley@cern.ch> +* Thorsten Schwander <thorsten.schwander@gmail.com> * Tiberiu Dondera <tiberiu.dondera@pronet-consulting.com> +* Tibor Simko <tibor.simko@cern.ch> * Tony Ohls <tony.ohls@cern.ch> * Tony Osborne <tony.osborne@cern.ch> * Travis Brooks <travis@slac.stanford.edu> * Trond Aksel Myklebust <trond.aksel.myklebust@cern.ch> * Valkyrie Savage <vasavage@gmail.com> * Vasanth Venkatraman <vasanth.venkatraman@cern.ch> * Vasyl Ostrovskyi <vo@imath.kiev.ua> * Victor Engmark <victor.engmark@cern.ch> +* Wojciech Ziolek <wojciech.ziolek@cern.ch> * Yannick Tapparel <yannick.tapparel@cern.ch> * Yoan Blanc <yoan.blanc@cern.ch> * Yohann Paris <yohann.paris@cern.ch> * Željko Kraljević <w.kraljevic@gmail.com> See also THANKS file. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 974b4425b..b6d82dbe4 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,266 +1,159 @@ -============== - Contributing -============== - -Bug reports, feature requests, and code contributions are encouraged -and welcome! +Contribution guide +================== -Bug reports and feature requests --------------------------------- +Interested in contributing to the Invenio project? There are lots of ways to +help. -If you find a bug or have a feature request, please search for -`already reported problems -<https://github.com/inveniosoftware/invenio/issues>`_ before -submitting a new issue. +.. rubric:: Code of conduct -Code contributions ------------------- +Overall, we're **open, considerate, respectful and good to each other**. We +contribute to this community not because we have to, but because we want to. +If we remember that, our :ref:`code-of-conduct` will come naturally. -We follow typical `GitHub flow -<https://guides.github.com/introduction/flow/index.html>`_. +.. rubric:: Get in touch -1. Fork this repository into your personal space. -2. Start a new topical branch for any contribution. Name it sensibly, - say ``improve-fix-search-user-preferences``. -3. Test your branch on a local site. If everything works as expected, - please `sign your commits - <http://invenio.readthedocs.io/en/latest/technology/git.html#r2-remarks-on-commit-log-messages>`_ - to indicate its quality. -4. Create `logically separate commits - <http://invenio.readthedocs.io/en/latest/technology/git.html#r1-remarks-on-commit-history>`_ - for logically separate things. -5. Please add any ``(closes #123)`` or ``(addresses #123)`` directives - in your commit log message if your pull request closes or addresses - an open issue. -6. Issue a pull request. If the branch is not quite ready yet, please - indicate ``WIP`` (=work in progress) in the pull request title. +See :ref:`getting-help` and :ref:`communication-channels`. Don't hesitate +to get in touch with the Invenio maintainers (listed in ``MAINTAINERS`` file). +The maintainers can help you kick start your contribution. -Developer Guidelines --------------------- +Types of contributions +---------------------- -Here is more detailed checklist of things to do when contributing code -to Invenio. +Report bugs +~~~~~~~~~~~ +- **Found a bug? Want a new feature?** Open a GitHub issue on the applicable + repository and get the conversation started (do search if the issue has + already been reported). Not sure exactly where, how, or what to do? + See :ref:`getting-help`. -1. **Before starting any wider-impact changes, submit a ticket and use a - discussion channel.** +- **Found a security issue?** Alert us privately at + `info@inveniosoftware.org <info@inveniosoftware.org>`_, this will allow us to + distribute a security patch before potential attackers look at the issue. - * Found a bug in a module and have a fix for it? Great, please - jump right in! +Translate +~~~~~~~~~ +- **Missing your favourite language?** Translate Invenio on + `Transifex <https://www.transifex.com/inveniosoftware/invenio/>`_ - * Have a new feature request or thinking of a new facility that - would impact several modules? Submit a ticket and discuss the - change before starting any implementation. +- **Missing context for a text string?** Add context notes to + translation strings or report the issue as a bug (see above). - * Small intra-module changes? Discuss even in small circles with - the module maintainer. +- **Need help getting started?** See our :ref:`translation-guide`. - * Big inter-module changes? Discuss in wider circle among module - maintainers and lead developers. Take advantage of the weekly - developer forum. +Write documentation +~~~~~~~~~~~~~~~~~~~ +- **Found a typo?** You can edit the file and submit a pull request directly on + GitHub. - * Ensure there is a consensus about functionality and design before - starting any implementation. +- **Debugged something for hours?** Spare others time by writing up a short + troubleshooting piece on + https://github.com/inveniosoftware/troubleshooting/. -2. **Publish your code under GNU General Public License.** +- **Wished you knew earlier what you know now?** Help write both non-technical + and technical topical guides. - * Use GNU General Public License header following our usual style. - Update copyright years. +Write code +~~~~~~~~~~ +- **Need help getting started?** See our :ref:`developers-guide`. - * If you include any code, style, or icons created by others, check - the original license information to make sure it can be included. - Do not forget to acknowledge the original author in the THANKS - file. When appropriate, commit in the original author's name, - and commit your changes on top of them. +- **Need help setting up your editor?** See our + :ref:`setting-up-your-environment` guide which helps your automate the + tedious tasks. - * Willing to include your code under CERN copyright? Please send - an email about this to the Lead Developer. Otherwise add a new - copyright line for your institution in the files you have - touched. +- **Want to refactor APIs?** Get in touch with the maintainers and get the + conversation started. -3. **Choose good starting point to build your topical branch upon.** +- **Troubles getting green light on Travis?** Be sure to check our + :ref:`style-guide` and the :ref:`setting-up-your-environment`. It will make + your contributor life easier. - * Fixing a bug in a given version? Start from ``maint-x.y``. Name - your topical branch ``johndoe/999-bibfoo-fix-xyzzy`` using ticket - number and a short branch description. +- **Bootstrapping a new awesome module?** Use our `Invenio cookiecutter +template <http://github.com/inveniosoftware/cookiecutter-invenio-module>`_. - * Introducing a new feature? Always start from ``master``. +Style guide (TL;DR) +------------------- +Travis CI is our style police officer who will check your pull +request against most of our :ref:`style-guide`, so do make sure you get a green +light from him. - * Must introduce new feature to ``maint-1.1``? Really? OK, so be - it, but make it configurable via new ``CFG_BIBFOO_XYZZY`` - configuration variable. Do not rely on its existence, since - people can upgrade/downgrade within ``v1.1.x`` point releases - frequently. Have it imported in a try/except manner and provide - fallback for older point releases. Example: - ``CFG_WEBSUBMIT_DOCUMENT_FILE_MANAGER_MISC`` in `47e4a33 - <https://github.com/inveniosoftware/invenio/commit/47e4a3364a9c84942fe9cddc88530466195663a6>`_. +**ProTip:** Make sure your editor is setup to do checking, linting, static +analysis etc. so you don't have to think. Need help setting up your editor? See +:ref:`setting-up-your-environment`. - * Introducing a new experimental feature? Start from ``next``. +Commit messages +~~~~~~~~~~~~~~~ +Commit message is first and foremost about the content. You are communicating +with fellow developers, so be clear and brief. -4. **Make things easily configurable and reusable by others.** +(Inspired by `How to Write a Git Commit Message +<https://chris.beams.io/posts/git-commit/>`_) - * Need some feature that may break existing functionality used by - other production sites? Need some feature that other production - sites may want to switch off? Take care and make things - configurable to be able to easily share the code. +1. `Separate subject from body with a blank line + <https://chris.beams.io/posts/git-commit/#separate>`_ +2. `Limit the subject line to 50 characters + <https://chris.beams.io/posts/git-commit/#limit-50>`_ +3. `Indicate the component follow by a short description <>`_ +4. `Do not end the subject line with a period + <https://chris.beams.io/posts/git-commit/#end>`_ +5. `Use the imperative mood in the subject line + <https://chris.beams.io/posts/git-commit/#imperative>`_ +6. `Wrap the body at 72 characters + <https://chris.beams.io/posts/git-commit/#wrap-72>`_ +7. `Use the body to explain what and why vs. how, using bullet points <>`_ - * Use ``get_tag_from_name('journal title')`` vs hard-coded - ``773__p``. +**ProTip**: Really! Spend some time to ensure your editor is top tuned. It will +pay off many-fold in the long run. See :ref:`setting-up-your-environment`. - * Enable/disable custom features via role-based access control - system, e.g. action ``usebaskets``. +For example:: - * Ensure configurability of functionality via ``CFG_BIBFOO_XYZZY`` - variables. + component: sumarize changes in 50 char or less - * Ensure configurability of code via ``pluginutils``. + * More detailed explanatory text, if necessary. Formatted using + bullet points, preferabely `*`. Wrapped to 72 characters. - * Writing service-specific code or service-specific configuration? - Use your service-specific overlay repository. + * Explain the problem that this commit is solving. Focus on why you + are making this change as opposed to how (the code explains that). + Are there side effects or other unintuitive consequences of this + change? Here's the place to explain them. - * Writing generally-interested code that may be reused by others? - Write against Invenio Atlantis defaults, not against local - service specific overlay assumptions and context. + * The blank line separating the summary from the body is critical + (unless you omit the body entirely); various tools like `log`, + `shortlog` and `rebase` can get confused if you run the two + together. + + * Use words like "Adds", "Fixes" or "Breaks" in the listed bullets to help + others understand what you did. -5. **Create logically separate commits for logically separate - things.** + * If your commit closes or addresses an issue, you can metion + it in any of the bullets after the dot. (closses #XXX) (addresses + #YYY) - * Fixing a minor problem on the site of the topic branch at hand? - Create separate topical branch or at least a separate logical - commit. + Co-authored-by: John Doe <john.doe@example.com> - * Having a basically working version and improving upon its - performance? Maintain two separate commits. +Pull requests +------------- +Need help making your first pull request? Check out the GitHub guide +`Forking Projects <https://guides.github.com/activities/forking/>`_. - * Committing partially working code and fixing it later? Squash - the commits together. +When making your pull request, please keep the following in mind: - * Commit early, commit often... all the while ensuring continuous - integration principles. Make sure the topical branch is - merge-ready at almost any given moment in time, even when not - completed. Hence use of configurability upfront. +- Create logically separate commits for logically separate things. +- Include tests and don't decrease test coverage. +- Do write documentation. We all love well-documented frameworks, right? +- Run tests locally using ``run-tests.sh`` script. +- Make sure you have the rights if you include third-party code (and do credit + the orignial creator). +- Green light on all GitHub status checks is required in order to merge your + PR. + +.. rubric:: Work in progress (WIP) - * See `git workflow documentation on rebasing - <http://invenio.readthedocs.io/en/latest/technology/git.html#r1-remarks-on-commit-history>`_ - for more. +Do publish your code as pull request sooner than later. Just prefix the pull +request title with ``WIP`` (=work in progress) if it is not quite ready. -6. **Use sensible commit messages and stamp them with QA and ticket - directives.** - - * Describe what the patch does so that the commit message is - self-understandable without reading the code. - - * If the patch closes a ticket, use ``(closes #123)`` ticket - directive. If the patch only addresses the issue, use - ``(addresses #123)`` ticket directive. - - * If you tested your code thoroughly and stand by its perfection, - use ``Signed-off-by`` commit QA stamp. If you reviewed the code - created by others, use ``Reviewed-by`` QA stamp. Helps to get - them onto fast integration track. - - * See `git workflow documentation on commit log messages - <http://invenio.readthedocs.io/en/latest/technology/git.html#r2-remarks-on-commit-log-messages>`_ - for more. - -7. **Include test cases with the code.** - - * Always write unit and functional tests alongside coding. Helps - making sure the code runs OK on all supported platforms. Helps - speeding up the review and integration processes. Helps - understanding the code written by others by looking at their unit - test cases. - -8. **Include documentation with the code.** - - * "It's not finished until it's documented." --This may originally - have been said by Tom Limoncelli. - - * "Documentation isn't done until someone else understands - it." --Originally submitted by William S. Annis on 12jan2000. - - * "Good code is its own best documentation. As you're about to add - a comment, ask yourself, 'How can I improve the code so that this - comment isn't needed?' Improve the code and then document it to - make it even clearer."--Steve McConnell, "Code Complete" - - * "If the code and the comments disagree, then both are probably - wrong." --attributed to Norm Schryer - - * "Incorrect documentation is often worse than no - documentation." --Bertrand Meyer" - -9. **Check the overall code kwalitee.** - - * Does your branch fully implement the functionality it promises to - implement? Are all corner cases covered? E.g. citation history - graph when there are no citations? - - * Are you changing DB schema? Write an `upgrade recipe - <http://invenio-upgrader.readthedocs.io/>`_. - - * Does your branch pass all our standard kwalitee tests? Have you - run `invenio-check-branch - <https://github.com/tiborsimko/invenio-devscripts#invenio-check-branch>`_ - locally? Does your branch pass Travis or Jenkins builds? - - * Name things properly. Use ``list_of_scores`` rather than - ``list2``. Use ``InvenioBibFooFatalError`` rather than - ``MyFatalError``. - - * Do not forget to sanitise all your input arguments. Escape your - HTML outputs to protect against XSS. Supply your ``run_sql()`` - arguments in a tuple to protect against SQL injection. Avoid - using ``eval()``. - - * Respect minimal requirements, e.g. write for Python-2.4 for - production ``maint-x.y`` branches that still require it. Use - Vagrant `virtual development environment` when necessary. - - * Make conditional use of optional dependencies, e.g. test - ``feedparser`` existence via ``try/except`` importing. Check - that the rest of the site still works OK without ``feedparser``. - -10. **Send the code for review and integration.** - - * Distinguish between design-review process (that should have - happened earlier, already in the first step) and the code-review - process (that happens now). - - * No API change, only bugfixes? All commits duly signed by - authors and responsible module maintainers aka integration - lieutenants? Fast integration track. - - * Possible API changes, possible user/admin feature changes? Need - to synchronise about needs and to ensure configurability and - compatibility? Slow integration track. - -11. **Help improving overall development, deployment, and operational - bandwidth.** - - * Developers can help by adopting good practices upfront early in - the process. - - * Reviewers can help by using QA stamps and fast integration - tracks in live sessions. - - * Testers can help by widening the test suite so that nightly - builds can be relied upon for deployment. - - * Administrators can help by sharing needs, requirements, - solutions, and "howto" recipes. - -12. **Share thoughts, needs, requirements, solutions, "howto" recipes - with others.** - - * Check existing list of known bugs and known feature requests for - any given module. Troubles with collections? Go to - `Modules/invenio-collections - <http://invenio.readthedocs.io/en/latest/modules/list.html#invenio-collections>`_. - - * Did you perform some service operation such as changing your - site URL? Did you log the several steps needed to achieve - this? Document them. - - * Have you tried to improve performance of some tools Invenio - relies on? Have you run experiments and obtained observations - and tips on MySQL performance? Document them. +.. rubric:: Allow edits from maintainers + +To speed up the integration process, it helps if on GitHub you `allow +maintainers to edit your pull request +<https://help.github.com/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork/>`_ +so they can fix small issues autonomously. diff --git a/docs/community/channels.rst b/docs/community/channels.rst new file mode 100644 index 000000000..12c914777 --- /dev/null +++ b/docs/community/channels.rst @@ -0,0 +1,104 @@ +.. _communication-channels: + +Communication channels +====================== + +Chatrooms +~~~~~~~~~ +Most day-to-day communication is happening in our chatrooms: + +- `Public chatroom <https://gitter.im/inveniosoftware/invenio>`_ (for everyone) +- `Developer chatroom <https://gitter.im/inveniosoftware/invenio>`_ (for + `members <https://github.com/orgs/inveniosoftware/people>`_ of inveniosoftware + GitHub organisation). + +If you want to join the developer chatroom, just ask for an invite on the +public chatroom. + +GitHub +~~~~~~ +Most of the developer communication is happening on GitHub. You are stroungly +encouraged to join +`<https://github.com/orgs/inveniosoftware/teams/developers>`_ team and watch +notifications from various `<https://github.com/inveniosoftware/>`_ +organisation repositories of interest. + +Invenio Developer Forum +~~~~~~~~~~~~~~~~~~~~~~~ +Monday afternoons at 16:00 CET/CEST time we meet physically at CERN and +virtually over videoconference to discuss interesting development topics. + +You can join our Monday forums from anywhere via videoconference. Here the +steps: + +- View the `agenda <https://indico.cern.ch/category/6046/>`_ + (`ical feed <https://indico.cern.ch/export/categ/6046.ics?from=-31d>`_). +- Install the videoconferencing client `Vidyo <https://vidyoportal.cern.ch/>`_. +- Join our `virtual room <https://vidyoportal.cern.ch/join/a6GP8E71EU>`_. + +Invenio User Group Workshop +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +We meet among Invenio users and developers from around the world at a yearly +Invenio User Group Workshop. The workshop consists of a series of +presentations, tutorials, practical exercises, and discussions on topics +related to Invenio digital library management and development. We exchange +knowledge and experiences and drive forward the forthcoming developments of +the Invenio platform. + +See list of `upcoming and past <https://indico.cern.ch/category/6240/>`_ +workshops. + +Project website +~~~~~~~~~~~~~~~ +Our project website, http://inveniosoftware.org, is used to show case Invenio. + +.. todo:: + + Make better description of project website. Add high level road map etc to + project website. + +Email +~~~~~ +You can get in touch with the Invenio management team on +`info@inveniosoftware.org <mailto:info@inveniosoftware.org>`_. + +In particular use above email address to report security related issues +privately to us, so we can distribute a security patch before potential +attackers look at the issue. + +Twitter +~~~~~~~ +The official Twitter account for Invenio software is used mostly for announcing +new releases and talks at conferences: + +- `<https://twitter.com/inveniosoftware>`_ + +Mailing lists +~~~~~~~~~~~~~ +The mailing lists are currently not very active and are primiarly listed here +for historical reasons. + +- ``project-invenio-announce@cern.ch``: Read-only moderated mailing + list to announce new Invenio releases and other major news concerning the + project. `(un)subscribe <https://simba3.web.cern.ch/simba3/SelfSubscription.aspx?groupName=project-invenio-announce>`_, + `archive <https://groups.cern.ch/group/project-invenio-announce/Lists/Archive/100.aspx>`_ +- ``project-invenio-general@cern.ch``: Originally used for discussion among + users and administrators of Invenio instances. The mailing list has mostly + been replaced by our public chatroom. + `(un)subscribe <https://simba3.web.cern.ch/simba3/SelfSubscription.aspx?groupName=project-invenio-general>`_, + `new archive <https://groups.cern.ch/group/project-invenio-general/Lists/Archive/100.aspx>`_, + `old archive <https://groups.cern.ch/group/project-cdsware-users/Lists/Archive/100.aspx>`_ +- ``project-invenio-devel@cern.ch``: Originally used for discussion among + Invenio developers. The mailing list has mostly been replaced by our + developer chatroom. + `(un)subscribe <https://simba3.web.cern.ch/simba3/SelfSubscription.aspx?groupName=project-invenio-devel>`_, + `new archive <https://groups.cern.ch/group/project-invenio-devel/Lists/Archive/100.aspx>`_, + `old archive <https://groups.cern.ch/group/project-cdsware-developers/Lists/Archive/100.aspx>`_ + +Note that all the mailing lists are also archived (as of the 20th of +July, 2011) on `The Mail Archive <http://www.mail-archive.com/>`__. + + +.. todo:: + + Setup an architecture team meeting between core maintainers. diff --git a/docs/community/contribution-guide.rst b/docs/community/contribution-guide.rst index ed0a66762..ac7b6bcf3 100644 --- a/docs/community/contribution-guide.rst +++ b/docs/community/contribution-guide.rst @@ -1,224 +1 @@ -Contribution guide -================== - -Interested in contributing to the Invenio project? There are lots of ways to -help. - -------- -Conduct -------- - -Overall, we're **considerate, open, respectful and good to each other**. We -contribute to this community not because we have to, but because we want to. -If we remember that, our -`Code of Conduct -<http://invenio.readthedocs.io/en/feature-ils/community/code-of-conduct.html>`_ -will come naturally. - --------------------------- -File Bugs and Enhancements --------------------------- - -Found a bug? Want to see a new feature? Have a request for the maintainers? -Open a Github issue in the applicable repository and we’ll get the -conversation started. - -**Found a security issue? Alert us privately at -<info@inveniosoftware.org>**, this will allow us to distribute a security -patch before potential attackers look at the issue. - -Our official communication channel is Gitter, we have one -`main chat room <https://gitter.im/inveniosoftware/invenio>`_, -although there are several other chat rooms for individual repositories. - -Don't know what the applicable repository for an issue is? Open up an issue -in the `Invenio <https://github.com/inveniosoftware/invenio>`_ repository or -chat with a maintainer in the -`Gitter main room <https://gitter.im/inveniosoftware/invenio>`_ -and we will make sure it gets to the right place. - -Additionally, take a look at our -`troubleshooting <https://github.com/inveniosoftware/troubleshooting/issues>`_ -documentation for common issues. - -Before opening a new issue it's helpful to search and see if anyone has -already reported the problem. You can search through the entire list of -issues in `GitHub <https://github.com/pulls?utf8=✓&q=user%3Ainveniosoftware>`_. - -------------- -Triage Issues -------------- - -If you don't have time to code, consider helping with triage. The community -will thank you for saving them time by spending yours. - -The purpose of issue triage process is to make sure all the Invenio issues -and tasks are well described, sorted out according to priorities into timely -milestones, and that they have well assigned a responsible person to tackle -them when the time comes. - -------------------- -Write documentation -------------------- - -We are always looking to improve our documentation. Most of our docs live in -the `Invenio <https://github.com/inveniosoftware/invenio>`_ repository. Simply -fork the project, update docs and send us a pull request (The same principle -applies for the individual Invenio modules). - -Writing documentation is not much different that writing code, please check -the `Contribute Code`_ section for more information about the whole process. - --------------------- -Improve Translations --------------------- - -Found a translation missing? We use transifex to handle our translation -string, take a look `here <https://www.transifex.com/inveniosoftware/invenio/>`_. - -If it your first time doing that, we have prepared a -`nice tutorial -<http://invenio.readthedocs.io/en/feature-ils/community/translation-guide.html>`_ -that you can follow. - ---------------- -Contribute Code ---------------- - -We are always looking for help improving the Invenio ecosystem, new -modules, tooling, and test coverage. Interested in contributing code? Let's -chat about it in the `Invenio's Gitter main chat room -<https://gitter.im/inveniosoftware/invenio>`_ or ask any of the core maintainers -to point you in the right direction. Make sure to check out issues tagged easy -fix, they are a good starting point. - -Before doing something that will significantly alter the behavior of any -Invenio module, such as a new feature, major refactoring, or -API changes, contributors should first open an issue presenting their case, -see `File Bugs and Enhancements`_, also you can ask for the opinion of any of the -core maintainers. - -Commit messages ---------------- - -(Inspired by `How to Write a Git Commit Message -<https://chris.beams.io/posts/git-commit/>`_) - -1. `Separate subject from body with a blank line - <https://chris.beams.io/posts/git-commit/#separate>`_ -2. `Limit the subject line to 50 characters - <https://chris.beams.io/posts/git-commit/#limit-50>`_ -3. `Indicate the component follow by a short description`_ -4. `Do not end the subject line with a period - <https://chris.beams.io/posts/git-commit/#end>`_ -5. `Use the imperative mood in the subject line - <https://chris.beams.io/posts/git-commit/#imperative>`_ -6. `Wrap the body at 72 characters - <https://chris.beams.io/posts/git-commit/#wrap-72>`_ -7. `Use the body to explain what and why vs. how using bullet points`_ - -For example:: - - component: sumarize changes in 50 char or less - - * More detailed explanatory text, if necessary. Formatted ussing - bullet points, preferabely `*`. Wrapped to 72 characters. - - * Explain the problem that this commit is solving. Focus on why you - are making this change as opposed to how (the code explains that). - Are there side effects or other unintuitive consequences of this - change? Here's the place to explain them. - - * The blank line separating the summary from the body is critical - (unless you omit the body entirely); various tools like `log`, - `shortlog` and `rebase` can get confused if you run the two - together. - - * Use words like "Adds", "Fixes" or "Breaks" to help others - understand what you did. - - * If your commit closes or addresses somehow an issue, you can metion - it in any of the bullets after the dot. (closses #XXX) (addresses - #YYY) - - Co-authored-by: John Doe <john.doe@example.com> - -Indicate the component follow by a short description -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -We know space is precious and 50 characters is not much for the subject line, -but maintainers and other people in general will appreciate if you can narrow -the focus of your commit in the subject. - -Normal components match to the python modules inside the repository, i.e. `api`, -`views`, or `config`. -There are other components which correspond to a wider scope like `tests` or -`docs`. -And finally there is third category which doesn't correspond to any file or -folder in particular: - -- `installation`: use it when modifying things like requirements files or `setup.py`. -- `release`: only to be used by maintainers. - -If one commit modifies more than one file, i.e. `api.py` and `views.py`, common -sense should be applied, what represents better the changes the commit makes? -Remember you can always as for the modules maintainer's opinion. - -Use the body to explain what and why vs. how using bullet points -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Take a look at the full diff and just think how much time you would be saving -fellow and future committers by taking the time to provide this context here and -now. If you don’t, it would probably be lost forever. - -In most cases, you can leave out details about how a change has been made. - -In most cases, you can leave out details about how a change has been made. Code -is generally self-explanatory in this regard (and if the code is so complex that -it needs to be explained in prose, that’s what source comments are for). Just -focus on making clear the reasons why you made the change in the first place—the -way things worked before the change (and what was wrong with that), the way they -work now, and why you decided to solve it the way you did. Using bullet points -will help you be precise and direct to the point. - -If you find your self writing a rather long commit message, maybe it's time to -step back and consider if you are doing too many changes in just one commit and -whether or not it's worth splitting it in smaller peaces. - -And remember, the future maintainer that thanks you for writing good commit -messages may be yourself! - -Submitting a pull request -------------------------- - -All proposed changes to any of the Invenio modules are made as GitHub pull -requests, if this is the first time you are making a contribution using -GitHub, please check `this <https://guides.github.com/activities/forking/>`_. - -Once you are ready to make your pull request, please keep in mind the -following: - -- Before creating your pull request run the `run-tests.sh` script, this will - help you discover possible side effects of your code and ensure it follows - `Invenio's style guidelines - <http://invenio.readthedocs.io/en/feature-ils/community/style-guide.html>`_, - check `Development Environment - <http://invenio.readthedocs.io/en/feature-ils/developersguide/development-environment.html>`_ - for more information on how you can run this script. -- Every pull request should include tests to check the expected behavior of - your changes and must not decrease test coverage. If it fixes a bug it - should include a test which proves the incorrect behavior. -- Documenting is part of the development process, no pull request will be - accepted if there is missing documentation. -- No pull request will be merged until all automatic checks are green and at - least one maintainer approves it. - - ------------ -Maintainers ------------ - -The Invenio project follows a similar maintainer phylosofy as `docker -<https://github.com/docker/docker/blob/master/MAINTAINERS>`_. If you want to -know more about it or take part, you can read our `Maintainer's guide -<http://invenio.readthedocs.io/en/feature-ils/community/maintainers-guide/index.html>`_. +.. include:: ../../CONTRIBUTING.rst diff --git a/docs/community/getting-help.rst b/docs/community/getting-help.rst new file mode 100644 index 000000000..124eadb18 --- /dev/null +++ b/docs/community/getting-help.rst @@ -0,0 +1,30 @@ +.. _getting-help: + +Getting help +============ + +Didn't find a solution to your problem the Invenio documentation? Here's how +you can get in touch with other users and developers: + +.. rubric:: Forum/Knowledge base + +- https://github.com/inveniosoftware/troubleshooting + +Ask questions or browse answers to exsiting questions. + +.. rubric:: Chatroom + +- https://gitter.im/inveniosoftware/invenio + +Probably the fastest way to get a reply is to join our chatroom. Here most +developers and maintainers of Invenio hangout during their regular working +hours. + +.. rubric:: GitHub + +- https://github.com/inveniosoftware + +If you have feature requests or want to report potential bug, you can do it by +opening an issue in one of the individual Invenio module repositories. In each +repository there is a ``MAINTAINERS`` file in the root, which lists the who +is maintaining the module. diff --git a/docs/community/getting-involved.rst b/docs/community/getting-involved.rst deleted file mode 100644 index 02239a5dd..000000000 --- a/docs/community/getting-involved.rst +++ /dev/null @@ -1,82 +0,0 @@ -Getting involved -================ - -Communication channels ----------------------- - -Chatrooms -~~~~~~~~~ -We use Gitter for both personal and group chat. Our main chat room is: - -- `<https://gitter.im/inveniosoftware/invenio>`_ - - -GitHub -~~~~~~ -Most of the developer communication is happening nowadays on GitHub, not on the -mailing lists. You are stroungly encouraged to join -`<https://github.com/orgs/inveniosoftware/teams/developers>`_ team and watch -notifications from various `<https://github.com/inveniosoftware/>`_ organisation -repositories of interest. - - -Invenio Developer Forum -~~~~~~~~~~~~~~~~~~~~~~~ -Every Monday at 16:00 CET/CEST we get together for an hour of live discussions. -We call it the "Invenio Developer Forum". It is possible to join via -videoconference. Please see dedicated `Invenio Developer Forum -<https://indico.cern.ch/category/6046/>`_ website with instructions and agenda. - - -Invenio User Group Workshop -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Twitter -~~~~~~~ -The official Twitter account for Invenio software is used mostly for announcing -new releases and talks at conferences: - -- `<https://twitter.com/inveniosoftware>`_ - -inveniosoftware.org -~~~~~~~~~~~~~~~~~~~ - - -Mailing lists -~~~~~~~~~~~~~ - -``project-invenio-announce@cern.ch`` - - Low-volume read-only moderated mailing list to announce new Invenio releases - and other major news concerning the project. Every Invenio user is strongly - encouraged to subscribe to this list. - - - `p-i-a (un)subscribe <https://simba3.web.cern.ch/simba3/SelfSubscription.aspx?groupName=project-invenio-announce>`_ - - `p-i-a new archives <https://groups.cern.ch/group/project-invenio-announce/Lists/Archive/100.aspx>`_ - - `p-i-a old archives <https://groups.cern.ch/group/project-cdsware-announce/Lists/Archive/100.aspx>`_ - - `p-i-a very old archives <http://cdsware.cern.ch/lists/project-cdsware-announce/archive/>`_ - -``project-invenio-general@cern.ch`` - - Possibly high-volume mailing list, intended for discussion among users and - administrators of Invenio instances. - - - `p-i-g (un)subscribe <https://simba3.web.cern.ch/simba3/SelfSubscription.aspx?groupName=project-invenio-general>`_ - - `p-i-g new archives <https://groups.cern.ch/group/project-invenio-general/Lists/Archive/100.aspx>`_ - - `p-i-g old archives <https://groups.cern.ch/group/project-cdsware-users/Lists/Archive/100.aspx>`_ - - `p-i-g very old archives <http://cdsware.cern.ch/lists/project-cdsware-users/archive/>`_ - -``project-invenio-devel@cern.ch`` - - Possibly high-volume mailing list, intended for discussion among Invenio - developers and hackers. - - - `p-i-d (un)subscribe <https://simba3.web.cern.ch/simba3/SelfSubscription.aspx?groupName=project-invenio-devel>`_ - - `p-i-d new archives <https://groups.cern.ch/group/project-invenio-devel/Lists/Archive/100.aspx>`_ - - `p-i-d old archives <https://groups.cern.ch/group/project-cdsware-developers/Lists/Archive/100.aspx>`_ - - `p-i-d very old archives <http://cdsware.cern.ch/lists/project-cdsware-developers/archive/>`_ - -Note that all the mailing lists are also archived (as of the 20th of -July, 2011) on `The Mail Archive <http://www.mail-archive.com/>`__. As -soon as possible we will upload there also all the previous historical -archives. diff --git a/docs/community/maintainers-guide/branches.rst b/docs/community/maintainers-guide/branches.rst index 0089bef49..eacd5d228 100644 --- a/docs/community/maintainers-guide/branches.rst +++ b/docs/community/maintainers-guide/branches.rst @@ -1,2 +1,51 @@ Understanding branches ====================== + +The official Invenio repository contains several branches for +maintenance and development purposes. We roughly follow the usual git +model as described in +`man 7 gitworkflows <http://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_ +and elsewhere. + +In summary, the new patchlevel releases (X.Y.Z) happen from the ``maint`` +branch, the new minor feature releases (X.Y) happen from the ``master`` +branch, and new major feature releases (X) happen after they mature in the +optional ``next`` branch. A more detailed description follows. + +``maint`` +~~~~~~~~~ + +This is the maintenance branch for the latest stable release. There +can be several maintenance branches for every release series +(**maint-0.99**, **maint-1.0**, **maint-1.1**), but typically we use only +``maint`` for the latest stable release. + +The code that goes to the maintenance branch is of bugfix nature +only. It should not alter DB table schema, Invenio config file +schema, local configurations in the ``etc`` folder or template function +parameters in a backward-incompatible way. If it contains any new +features, then they are switched off in order to be fully compatible +with the previous releases in this series. Therefore, for +installations using any Invenio released X.Y series, it should be +always safe to upgrade the system at any moment in time by (1) backing +up their ``etc`` folder containing local configuration, (2) installing +the corresponding ``maint-X.Y`` branch updates, and (3) rolling back the +``etc`` folder with their customizations. This upgrade process will be +automatized in the future via special ``inveniomanage`` options. + +``master`` +~~~~~~~~~~ + +The ``master`` branch is where the new features are being developed and +where the new feature releases are being made from. The code in +``master`` is reviewed and verified, so that it should be possible to +make a new release out of this branch almost at any given point in +time. However, Invenio installations that would like to track this +branch should be aware that DB table definitions are not frozen and +may change, the config is not frozen and may change, etc, until the +release time. So while ``master`` is relatively stable for usage, it +should be treated with extreme care, because updates between day D1 +and day D2 may require DB schema and ``etc`` configuration changes that +are not covered by usual ``inveniomanage`` update statements, so people +should be prepared to study the differences and update DB schemata and +config files themselves. diff --git a/docs/community/maintainers-guide/index.rst b/docs/community/maintainers-guide/index.rst index c87f1971d..23fe920ec 100644 --- a/docs/community/maintainers-guide/index.rst +++ b/docs/community/maintainers-guide/index.rst @@ -1,12 +1,12 @@ -Maintainer's guide -================== +Maintainer's guide TODO +======================= .. todo:: Fill with new proposal .. toctree:: :maxdepth: 2 overview releasing setup-repository branches diff --git a/docs/processes/integrating.rst b/docs/community/maintainers-guide/integrating.rst similarity index 78% rename from docs/processes/integrating.rst rename to docs/community/maintainers-guide/integrating.rst index aed8fda23..21aa882de 100644 --- a/docs/processes/integrating.rst +++ b/docs/community/maintainers-guide/integrating.rst @@ -1,62 +1,45 @@ .. This file is part of Invenio Copyright (C) 2015, 2016 CERN. Invenio is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. Invenio is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. ============= Integrating ============= -:: - - Covered with tests - Instantly I’d like to merge - In this dream of ours! - -—after Ochi Etsujin (1656?-1739?) - Integrating principles ====================== .. _check-it-from-the-helicopter: 1. **Check it from the helicopter.** If it ain’t green, it ain’t finished. If it ain’t understandable, it ain’t documented. .. _beware-of-inter-module-relations: 2. **Beware of inter-module relations.** Changing API? Perhaps this pull request may break other modules. Check outside usage. Check the presence of ``versionadded``, ``versionmodified``, ``deprecated`` docstring directives. .. _beware-of-inter-service-relations: 3. **Beware of inter-service relations.** Changing pre-existing tests? Perhaps this pull request does not fit the needs of other Invenio services. -.. _check-the-signature-karma: - -4. **Check the signature karma.** If it ain’t signed, it ain’t finished. - -.. _check-the-counter-signature-karma: - -5. **Check the counter-signature karma.** If it ain’t counter-signed, it ain’t - finished. Check for "Reviewed-by" commit signatures. Check for "LGTM" or - ":shipit:" pull request signatures. - .. _avoid-self-merges: 6. **Avoid self merges.** Each pull request should be seen by another pair of eyes. Was it authored and reviewed by two different persons? Good. Were the two different persons coming from two different service teams? Better. diff --git a/docs/community/maintainers-guide/overview.rst b/docs/community/maintainers-guide/overview.rst index 35ae4e0fa..a3d951c68 100644 --- a/docs/community/maintainers-guide/overview.rst +++ b/docs/community/maintainers-guide/overview.rst @@ -1,105 +1,105 @@ Overview ======== - + What is a maintainer? --------------------- (Clearly inspired by the `Docker <https://github.com/docker/docker/blob/master/MAINTAINERS>`_ project) There are different types of maintainers in the Invenio project, with -different responsibilities, but all of them have this **rights and +different responsibilities, but all of them have this **rights and responsibilities** in common: 1. Have merge rights in the repositories they are maintainers of, but no pull request can be merged until all checks have passed and at least one maintainer signs off. (If one maintainer is making a pull request another maintainer should sign off, this will prevent self merges) 2. Have the final word about architectural or API significant changes, ensuring always that the [Invenio deprecation policies](#orgheadline1) are followed. 3. Will review pull requests within a reasonable time range, offering constructive and objective comments in a respectful manner. 4. Will participate in feature development and bug fixing, proactively verifying that the nightly builds are successful. 5. Will prepare releases following the Invenio standards. 6. Will answer questions and help users in the `Invenio Gitter chat room <https://gitter.im/inveniosoftware/invenio>`_. -7. +7. Core maintainers ---------------- The core maintainers are the architectural team who shapes and drives the Invenio project and, as a consequence, they are the ultimate reponsible of -the success of it. +the success of it. They are ghostbusters of the project: when there's a problem others can't solve, they show up and fix it with bizarre devices and weaponry. Some maintainers work on the project Invenio full-time, although this is not a requirement. For each release (including minor releases), a "release captain" is assigned by the core maintainers from the pool of module maintainers. Rotation is encouraged across all maintainers, to ensure the release process is clear and up-to-date. The release can't be done without a core maintainer -approvals. +approvals. Any of the core maintainers can propose new module maintainers at any time, see `Becoming a maintainer`_ for more information. Module maintainers ------------------ Module maintainers are exceptionally knowledgeable about some but not necessarily all areas of the Invenio project, and are often selected due to specific domain knowledge that complements the project (but a willingness to continually contribute to the project is most important!). The duties of a module maintainer are very similar to those of a core maintainer, but they are limited to modules of the Invenio project where the module maintainer is knowledgeable. hose who have write access to the Invenio-X repository**. All maintainers can review pull requests and add LGTM labels as appropriate, in fact everyone is encourage to do so! Becoming a maintainer --------------------- Don't forget: being a maintainer is a time investment. Make sure you will have time to make yourself available. You don't have to be a maintainer to make a difference on the project! Usually to become a module maintainer, one of the core maintainers makes a pull request in the opensource project to propose the new maintainer. This pull request needs the approval from other core maintainer and from at least one of the module maintainers (if the module has any). To become a core maintainer the process is slightly different. Before being a core maintainer canditate one needs the make sustained contributions to the project over a period of time (usually more than 3 months), show willingness to help Invenio users on GitHub and in the `Invenio Gitter chat room <https://gitter.im/inveniosoftware/invenio>`_, and, overall, a friendly attitude. Once the avobe is out of question, the core maintainer who sponsors the future one will present him to the team and, if he gets the confiance of all of the current core maintaners, his sponsor will make a pull request to the opensource repository adding his name to the list. Stepping down as maintainer --------------------------- Stepping down as a maintainer is done also via pull request to the opensource GitHub repository. It can be the maintainer himself who makes the pull request and, as before, this type of pull requests need to be approved by one core maintainer and at -least one of the module maintainers (if any). +least one of the module maintainers (if any). Exceptionally the core maintainers can propose another maintainer, core or module maintainer, to stepdown. All core maintainers must unanimously agree before making any pull request. In both cases, we encourage the maintainers to give a brief explanation of their reasons to step down. diff --git a/docs/community/maintainers-guide/releasing.rst b/docs/community/maintainers-guide/releasing.rst index 5d132dae1..468373813 100644 --- a/docs/community/maintainers-guide/releasing.rst +++ b/docs/community/maintainers-guide/releasing.rst @@ -1,2 +1,48 @@ Making a release ================ + +.. _cross-check-ci-green-lights: + +1. **Cross-check CI green lights.** Are all Travis builds green? Is nightly + Jenkins build green? + +.. _cross-check-read-the-docs-documentation-builds: + +2. **Cross-check Read The Docs documentation builds.** Are docs building fine? + Is this check done as part of the continuous integration? If not, add it. + +.. _cross-check-demo-site-builds: + +3. **Cross-check demo site builds.** Is demo site working? + +.. _check-author-list: + +5. **Check author list.** Are all committers listed in AUTHORS file? Use + ``kwalitee check authors``. Add newcomers. Is this check done as part of the + continuous integration? If not, add it. + +.. _update-i18n-message-catalogs: + +6. **Update I18N message catalogs.** + +.. _update_version_number: + +7. **Update version number.** Stick to `semantic versioning + <http://semver.org/>`_. + +.. _generate-release-notes: + +8. **Generate release notes.** Use `kwalitee prepare release v1.1.0..` to + generate release notes. Use empty commits with "AMENDS" to amend wrong past + messages before releasing. + +.. _tag-it-push-it-: + +10. **Tag it. Push it.** Sign the tag with your GnuPG key. Push it to PyPI. Is + the PyPI deployment done automatically as part of the continuous + integration? If not, add it. + +.. _bump-it: + +11. **Bump it.** Don't forget the issue the pull request with a post-release + version bump. Use ``.devYYYYMMDD`` suffix. diff --git a/docs/processes/triaging.rst b/docs/community/maintainers-guide/triaging.rst similarity index 94% rename from docs/processes/triaging.rst rename to docs/community/maintainers-guide/triaging.rst index bf1f14792..01b8d99c4 100644 --- a/docs/processes/triaging.rst +++ b/docs/community/maintainers-guide/triaging.rst @@ -1,224 +1,207 @@ .. This file is part of Invenio Copyright (C) 2015, 2016 CERN. Invenio is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. Invenio is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. ========== Triaging ========== -:: - - No milestone - No assignee - A lonely feeling - —-after Yosa Buson (1716-1784) - Triaging principles =================== The purpose of `issue triage process <https://en.wikipedia.org/w/index.php?title=Software_bug&redirect=no#Bug_management>`_ is to make sure all the Invenio issues and tasks are well described, sorted out according to priorities into timely milestones, and that they have well assigned a responsible person to tackle them. The triage process is done collectively by the representatives of various Invenio distributed teams. The triage team members make sure of the big picture, cross-consider issues and tasks among interested services, help to note down, understand, prioritise, and follow-upon them. .. _every-issue-should-have-an-assignee: 1. **Every issue should have an assignee.** Issues without assignees are sad and likely to remain so. Each issue should have a driving force behind it. .. _every-issue-should-have-a-milestone: 2. **Every issue should have a milestone.** Issues without milestones are sad and likely to remain unaddressed. .. _use-additional-type-and-priority-labels: 3. **Use additional type and priority labels.** Helps to find related issues out quickly. .. _use-additional-service-labels: 4. **Use additional service labels.** Helps to distinguish which issues are of utmost importance to which services. Helps to keep a service-oriented dashboard overview. -.. _silent-since-a-month-ping-responsible: - -5. **Silent since a month? Ping responsible.** An issue shouldn't be opened - without update for more than a month. - .. _nobody-in-sight-to-work-on-this-discuss-and-triage: 6. **Nobody in sight to work on this? Discuss and triage.** The triage team should take action if there is no natural candidate to work on an issue. .. _no-time-to-realistically-tackle-this-use-someday-or-close: 7. **No time to realistically tackle this? Use "Someday" or close.** We don't want to have thousands of open issues. Issues from the someday open or closed pool can be revived later, should realistic manpower be found. -.. _no-reply-ping-inveniosoftware-triagers: - -8. **No reply? Ping @inveniosoftware/triagers** The triage team should take - action if there is no update on an issues for more than a month. - Triaging team ============= Invenio triaging team consists of persons who manipulate issues, create labels, attribute assignments, follow up progress, and collaboratively decide on milestones for various Invenio projects on GitHub. To enter a triaging team, the following conditions must be met: 1. The person is an established Invenio scrum master or developer who knows well the wider project ecosystem. E.g. worked for more than N1 years on the project OR maintained more than N2 modules OR committed more than N3 lines of code to N4 different modules. (For respectably large values of N.) 2. The person will use triaging rights for manipulating tickets only; never for pushing code. Since GitHub ticket-manipulation rights are indistinguishable from GitHub code-pushing rights, the persons in the "Triagers" team should take extra care to avoid accidental mishaps in this direction. (Such as doing ``git push myorigin master -f`` and realising only afterwards that "oops myorigin was wrongly set so now I have accidentally replaced the whole Invenio canonical project commit history".) The code pushing is being done by the "Integrators", not by the "Triagers". 3. The person will endorse social contract related to participation in the collaborative consensual triaging and milestone decision-making process. The triaging team will represent various Invenio developer teams and services, participating together with the release management team on decisions related to the roadmap milestones and releases. Triaging process ================ The process of triaging issues is being done continuously. This usually means that labels are being attached to issues, assignments are being decided, progress is being tracked, dependencies being clarified, questions being answered, etc. The triaging team meets regularly (say once every 1-2 weeks) to go over the list of open issues for any catch-up, follow-up, and re-classification of issues with respect to milestones. Issue labels ============ The issues are attributed namespaced labels indicating the following issue properties: * type: - `t_bug`: bug fix - `t_enhancement`: new feature or improvement of existing feature * priority: - `p_blocker`: highest priority, e.g. breaks home page - `p_critical`: higher priority, e.g. test case broken - `p_major`: normal priority, used for most tickets - `p_minor`: less priority, less visible user impact - `p_trivial`: lowest priority, cosmetics * component: - `c_WebSearch`: search component - `c_WebSubmit`: submit component - etc * status: - `in_work`: developer works on the topical branch - `in_review`: reviewer works on reviewing the work done - `in_integration`: integrator works on checking interplay with other services * resolution: - `r_fixed`: issue fixed - `r_invalid`: issue is not valid - `r_wontfix`: issue will not be dealt with for one reason or another - `r_duplicate`: issue is a duplicate of another issue - `r_question`: issue is actually a user question - `r_rfc`: issue is actually an open RFC * branch: - `maint-x.y`: issue applies to Invenio maint-x.y branch - `master`: issue applies to Invenio master branch - `next`: issue applies to Invenio next branch - `pu`: issue applies to Invenio pu branch * version: - `v0.99.1`: issue was observed on version v0.99.1 - `v1.1.3`: issue was observed on version v1.1.3 - etc The label types and values are coming from our Trac past and may be amended e.g. to take into account new component names in Invenio v2.0. Milestones and releases ======================= Issues may be attributed milestones that are closely related with feature-dependent and/or time-dependent release schedule of Invenio releases. There are two kinds of milestones: "release-oriented" milestones (say v1.1.7) and "someday" milestones (say v1.1.x) for each given release series (v1.1 in this case). The release-oriented milestones may have dates attached to them; the someday milestone may not. Typically, a new issue is given (a) the closest milestone in the given release series if its urgency is high, or (b) a later milestone in the given release series depending on the estimated amount of work and available resources, or is (c) left in the catch-all someday milestone out of which the issue can be later cherry-picked and moved to one of the concrete release-oriented milestones depending on available resources. Example: after Invenio v1.4.0 is released, all incoming bug reports for this version will go to the "someday" milestone for this release series, i.e. to "v1.4.x". A new XSS vulnerability issue will go straight to the next milestone "v1.4.1" because its release is urgent. A typo in an English output phrase in the basket module will remain in the someday milestone "v1.4.x" until it is picked for one of later releases, say v1.4.7, depending on available resources in the basket team. The triaging team together with the release management team will periodically review issues in a given release series and decide upon the set of issues going into a concrete release-oriented milestone (say these 15 issues for v1.4.1 milestone) after which the issue set is freezed and a sprint may be co-organised to meet the target deadline. Once all the issues have been solved, a new Invenio bug-fix release v1.4.1 is published and the release-oriented triaging cycle starts anew with v1.4.2. (Note that someday milestones are usually more useful for new feature releases; they might remain relatively empty for bug fix releases.) diff --git a/docs/community/releases.rst b/docs/community/releases.rst index df87ca9bf..d19818f13 100644 --- a/docs/community/releases.rst +++ b/docs/community/releases.rst @@ -1,193 +1,141 @@ .. This file is part of Invenio Copyright (C) 2015, 2016, 2017 CERN. Invenio is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. Invenio is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. Releases ======== -.. todo:: - - Move to versioning scheme to maintainers guide. Keep list of - releases. - -Release numbering scheme ------------------------- - -Invenio stable releases use the classical major.minor.patchlevel -release version numbering scheme that is commonly used in the -GNU/Linux world and elsewhere. Each release is labelled by:: - - major.minor.patchlevel - -release version number. For example, a release version 4.0.1 means:: - - 4 - 4th major version, i.e. the whole system has been already - 4th times either fully rewritten or at least in its very - essential components. The upgrade from one major version - to another may be rather hard, may require new prerequisite - technologies, full data dump, reload and reindexing, as - well as other major configuration adapatations, possibly - with an important manual intervention. - - 0 - 0th minor version, i.e. the first minor release of the 4th - major rewrite. (Increments go usually 4.1, 4.2, ... 4.9, - 4.10, 4.11, 4.12, ... until some important rewrite is done, - e.g. the database philosophy dramatically changes, leading - to a non-trivial upgrade, and then we have either higher - 4.x in the series or directly 5.0.0.) The upgrade from one - minor version to another may be laborious but is relatively - painless, in that some table changes and data manipulations - may be necessary but they are somewhat smaller in nature, - easier to grasp, and possibly done by a fully automated - script. - - 1 - 1st patch level release to 4.0 series, fixing bugs in 4.0.0 - but not adding any substantially new functionality. That - is, the only new functionality that is added is that of a - bug fix nature. The upgrade from one patch level to - another is usually very straightforward. - - (Packages often seem to break this last rule, e.g. Linux - kernel adopting new important functionality (such as - ReiserFS) within the stable 2.4.x branch. It can be easily - seen that it is somewhat subjective to judge what is - qualitatively more like a minor new functionality and what - is more like a patch to the existing behaviour. We have - tried to distinguish this with respect to whether the table - structure and/or the technology change require small or - large upgrade jobs and eventual manual efforts.) - -So, if we have a version 4.3.0, a bug fix would mean to release 4.3.1, -some minor new functionality and upgrade would mean to release 4.4.0, -some important database structure rewrite or an imaginary exchange of -Python for Common Lisp would mean to release 5.0.0, etc. - We follow `semantic versioning <http://semver.org/>`_ and `PEP-0440 <https://www.python.org/dev/peps/pep-0440/>`_ release numbering practices. Invenio v3.x ------------ -*Not released yet; however a developer preview is available on GitHub.* +*Unreleased* Invenio v3.0 will be released when the Invenio code base is fully split into a set of standalone independent Python packages. Invenio v2.x ------------ -*Semi-stable codebase.* +*Semi-stable* + +Invenio v2.x code base is a hybrid architecture that uses Flask web +development framework combined with Invenio v1.x framework. + +.. note:: -Invenio v2.x code base is our new code base architecture that uses Flask web -development framework. The most important modules take fully profit from the new -architecture (e.g. search, deposit), however some modules still rely on previous -v1.x legacy code base (e.g. baskets). Therefore its production suitability -depends on your use case. + The 2.x code base is not suitable for production systems, and will not + receive any further development nor security fixes. Released versions include: Invenio v2.1: * `v2.1.1 <https://github.com/inveniosoftware/invenio/releases/tag/v2.1.1>`_ - released 2015-09-01 * `v2.1.0 <https://github.com/inveniosoftware/invenio/releases/tag/v2.1.0>`_ - released 2015-06-16 Invenio v2.0: * `v2.0.6 <https://github.com/inveniosoftware/invenio/releases/tag/v2.0.6>`_ - released 2015-09-01 * `v2.0.5 <https://github.com/inveniosoftware/invenio/releases/tag/v2.0.5>`_ - released 2015-07-17 * `v2.0.4 <https://github.com/inveniosoftware/invenio/releases/tag/v2.0.4>`_ - released 2015-06-01 * `v2.0.3 <https://github.com/inveniosoftware/invenio/releases/tag/v2.0.3>`_ - released 2015-05-15 * `v2.0.2 <https://github.com/inveniosoftware/invenio/releases/tag/v2.0.2>`_ - released 2015-04-17 * `v2.0.1 <https://github.com/inveniosoftware/invenio/releases/tag/v2.0.1>`_ - released 2015-03-20 * `v2.0.0 <https://github.com/inveniosoftware/invenio/releases/tag/v2.0.0>`_ - released 2015-03-04 Invenio v1.x ------------ -*Stable codebase.* +*Stable* Invenio v1.x code base is suitable for stable production. It uses legacy technology and custom web development framework. +.. note:: + + Invenio v1.x is in feature freeze and will only receive important bug and + security fixes. + Released versions include: Invenio v1.2: * `v1.2.2 <https://github.com/inveniosoftware/invenio/releases/tag/v1.2.2>`_ - released 2016-11-25 * `v1.2.1 <https://github.com/inveniosoftware/invenio/releases/tag/v1.2.1>`_ - released 2015-05-21 * `v1.2.0 <https://github.com/inveniosoftware/invenio/releases/tag/v1.2.0>`_ - released 2015-03-03 Invenio v1.1: * `v1.1.7 <https://github.com/inveniosoftware/invenio/releases/tag/v1.1.7>`_ - released 2016-11-20 * `v1.1.6 <https://github.com/inveniosoftware/invenio/releases/tag/v1.1.6>`_ - released 2015-05-21 * `v1.1.5 <https://github.com/inveniosoftware/invenio/releases/tag/v1.1.5>`_ - released 2015-03-02 * `v1.1.4 <https://github.com/inveniosoftware/invenio/releases/tag/v1.1.4>`_ - released 2014-08-31 * `v1.1.3 <https://github.com/inveniosoftware/invenio/releases/tag/v1.1.3>`_ - released 2014-02-25 * `v1.1.2 <https://github.com/inveniosoftware/invenio/releases/tag/v1.1.2>`_ - released 2013-08-19 * `v1.1.1 <https://github.com/inveniosoftware/invenio/releases/tag/v1.1.1>`_ - released 2012-12-21 * `v1.1.0 <https://github.com/inveniosoftware/invenio/releases/tag/v1.1.0>`_ - released 2012-10-21 Invenio v1.0: * `v1.0.10 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.10>`_ - released 2016-11-09 * `v1.0.9 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.9>`_ - released 2015-05-21 * `v1.0.8 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.8>`_ - released 2015-03-02 * `v1.0.7 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.7>`_ - released 2014-08-31 * `v1.0.6 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.6>`_ - released 2014-01-31 * `v1.0.5 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.5>`_ - released 2013-08-19 * `v1.0.4 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.4>`_ - released 2012-12-21 * `v1.0.3 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.3>`_ - released 2012-12-19 * `v1.0.2 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.2>`_ - released 2012-10-19 * `v1.0.1 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.1>`_ - released 2012-06-28 * `v1.0.0 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.0>`_ - released 2012-02-29 * `v1.0.0-rc0 <https://github.com/inveniosoftware/invenio/releases/tag/v1.0.0-rc0>`_ - released 2010-12-21 Invenio v0.x ------------ -*Old codebase.* - Invenio v0.x code base was developed and used in production instances since 2002. The code base is interesting only for archaeological purposes. Released versions include: * `v0.99.9 <https://github.com/inveniosoftware/invenio/releases/tag/v0.99.9>`_ - released 2014-01-31 * `v0.99.8 <https://github.com/inveniosoftware/invenio/releases/tag/v0.99.8>`_ - released 2013-08-19 * `v0.99.7 <https://github.com/inveniosoftware/invenio/releases/tag/v0.99.7>`_ - released 2012-12-18 * `v0.99.6 <https://github.com/inveniosoftware/invenio/releases/tag/v0.99.6>`_ - released 2012-10-18 * `v0.99.5 <https://github.com/inveniosoftware/invenio/releases/tag/v0.99.5>`_ - released 2012-02-21 * `v0.99.4 <https://github.com/inveniosoftware/invenio/releases/tag/v0.99.4>`_ - released 2011-12-19 * `v0.99.3 <https://github.com/inveniosoftware/invenio/releases/tag/v0.99.3>`_ - released 2010-12-13 * `v0.99.2 <https://github.com/inveniosoftware/invenio/releases/tag/v0.99.2>`_ - released 2010-10-20 * `v0.99.1 <https://github.com/inveniosoftware/invenio/releases/tag/v0.99.1>`_ - released 2008-07-10 * `v0.99.0 <https://github.com/inveniosoftware/invenio/releases/tag/v0.99.0>`_ - released 2008-03-27 * `v0.92.1 <https://github.com/inveniosoftware/invenio/releases/tag/v0.92.1>`_ - released 2007-02-20 * `v0.92.0. <https://github.com/inveniosoftware/invenio/releases/tag/v0.92.0>`_ - released 2006-12-22 * `v0.90.1 <https://github.com/inveniosoftware/invenio/releases/tag/v0.90.1>`_ - released 2006-07-23 * `v0.90.0 <https://github.com/inveniosoftware/invenio/releases/tag/v0.90.0>`_ - released 2006-06-30 * `v0.7.1 <https://github.com/inveniosoftware/invenio/releases/tag/v0.7.1>`_ - released 2005-05-04 * `v0.7.0 <https://github.com/inveniosoftware/invenio/releases/tag/v0.7.0>`_ - released 2005-04-06 * `v0.5.0 <https://github.com/inveniosoftware/invenio/releases/tag/v0.5.0>`_ - released 2004-12-17 * `v0.3.3 <https://github.com/inveniosoftware/invenio/releases/tag/v0.3.3>`_ - released 2004-07-16 * `v0.3.2 <https://github.com/inveniosoftware/invenio/releases/tag/v0.3.2>`_ - released 2004-05-12 * `v0.3.1 <https://github.com/inveniosoftware/invenio/releases/tag/v0.3.1>`_ - released 2004-03-12 * `v0.3.0 <https://github.com/inveniosoftware/invenio/releases/tag/v0.3.0>`_ - released 2004-03-05 * `v0.1.2 <https://github.com/inveniosoftware/invenio/releases/tag/v0.1.2>`_ - released 2003-12-21 * `v0.1.1 <https://github.com/inveniosoftware/invenio/releases/tag/v0.1.1>`_ - released 2003-12-19 * `v0.1.0 <https://github.com/inveniosoftware/invenio/releases/tag/v0.1.0>`_ - released 2003-12-04 * `v0.0.9 <https://github.com/inveniosoftware/invenio/releases/tag/v0.0.9>`_ - released 2002-08-01 diff --git a/docs/community/style-guide.rst b/docs/community/style-guide.rst index 20140dba5..2e2dab0fe 100644 --- a/docs/community/style-guide.rst +++ b/docs/community/style-guide.rst @@ -1,2 +1,104 @@ -Style guide -=========== +.. _style-guide: + +Style guide TODO +================ + +Python +------ +We follow `PEP-8 <https://www.python.org/dev/peps/pep-0008/>`_ and `PEP-257 +<https://www.python.org/dev/peps/pep-0257/>`_ and sort imports via ``isort``. +Please plug corresponding linters such as ``flake8`` to your editor. + + +Commit message +-------------- + +.. todo:: + + Needs to be combined from existing parts and write the missing parts. + +Indicate the component follow by a short description +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We know space is precious and 50 characters is not much for the subject line, +but maintainers and other people in general will appreciate if you can narrow +the focus of your commit in the subject. + +Normal components match to the python modules inside the repository, i.e. `api`, +`views`, or `config`. +There are other components which correspond to a wider scope like `tests` or +`docs`. +And finally there is third category which doesn't correspond to any file or +folder in particular: + +- `installation`: use it when modifying things like requirements files or `setup.py`. +- `release`: only to be used by maintainers. + +If one commit modifies more than one file, i.e. `api.py` and `views.py`, common +sense should be applied, what represents better the changes the commit makes? +Remember you can always as for the modules maintainer's opinion. + +Use the body to explain what and why vs. how using bullet points +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Take a look at the full diff and just think how much time you would be saving +fellow and future committers by taking the time to provide this context here and +now. If you don’t, it would probably be lost forever. + +In most cases, you can leave out details about how a change has been made. + +In most cases, you can leave out details about how a change has been made. Code +is generally self-explanatory in this regard (and if the code is so complex that +it needs to be explained in prose, that’s what source comments are for). Just +focus on making clear the reasons why you made the change in the first place—the +way things worked before the change (and what was wrong with that), the way they +work now, and why you decided to solve it the way you did. Using bullet points +will help you be precise and direct to the point. + +If you find your self writing a rather long commit message, maybe it's time to +step back and consider if you are doing too many changes in just one commit and +whether or not it's worth splitting it in smaller peaces. + +And remember, the future maintainer that thanks you for writing good commit +messages may be yourself! + +Submitting a pull request +------------------------- + +All proposed changes to any of the Invenio modules are made as GitHub pull +requests, if this is the first time you are making a contribution using +GitHub, please check `this <https://guides.github.com/activities/forking/>`_. + +Once you are ready to make your pull request, please keep in mind the +following: + +- Before creating your pull request run the `run-tests.sh` script, this will + help you discover possible side effects of your code and ensure it follows + `Invenio's style guidelines + <http://invenio.readthedocs.io/en/feature-ils/community/style-guide.html>`_, + check `Development Environment + <http://invenio.readthedocs.io/en/feature-ils/developersguide/development-environment.html>`_ + for more information on how you can run this script. +- Every pull request should include tests to check the expected behavior of + your changes and must not decrease test coverage. If it fixes a bug it + should include a test which proves the incorrect behavior. +- Documenting is part of the development process, no pull request will be + accepted if there is missing documentation. +- No pull request will be merged until all automatic checks are green and at + least one maintainer approves it. + + +----------- +Maintainers +----------- + +The Invenio project follows a similar maintainer phylosofy as `docker +<https://github.com/docker/docker/blob/master/MAINTAINERS>`_. If you want to +know more about it or take part, you can read our `Maintainer's guide +<http://invenio.readthedocs.io/en/feature-ils/community/maintainers-guide/index.html>`_. + + + +FAQ +--- +- diff --git a/docs/community/translation-guide.rst b/docs/community/translation-guide.rst index 3573b9552..a9c3169f2 100644 --- a/docs/community/translation-guide.rst +++ b/docs/community/translation-guide.rst @@ -1,2 +1,8 @@ -Translation guide -================= +.. _translation-guide: + +Translation guide TOOD +====================== + +.. todo:: + + Write translation guide and possibly remove ABOUT-NLS. diff --git a/docs/developersguide/development-environment.rst b/docs/developersguide/development-environment.rst index 12ed9b0aa..afda6586f 100644 --- a/docs/developersguide/development-environment.rst +++ b/docs/developersguide/development-environment.rst @@ -1,23 +1,29 @@ -.. _set-up-environment: +.. _setting-up-your-environment: Setting up your development environment ======================================= +Some rules should be applied when developing for Invenio. Here are some hints +to set up your environment so these rules will be respected. -Some rules should be applied when developing for Invenio. Here are some hints to set up your environment so these rules will be respected. +Git +--- Set up git ----------- +~~~~~~~~~~ -Git should be aware of your name and your e-mail address. To do so, run these commands: +Git should be aware of your name and your e-mail address. To do so, run these +commands: .. code-block:: bash git config --global user.name "Nice Unicorn" git config --global user.email "nice@unicorn.com" -Set up your editor ------------------- -The most important rules are to make your editor print 4 spaces for indentation (instead of tabs) and limit the number of characters per line to 79. +Editor +------ + +The most important rules are to make your editor print 4 spaces for indentation +(instead of tabs) and limit the number of characters per line to 79. Then, you can add automatic PEP8 checks if you want. diff --git a/docs/developersguide/git.rst b/docs/developersguide/git.rst index d66cacdde..3ea44ca42 100644 --- a/docs/developersguide/git.rst +++ b/docs/developersguide/git.rst @@ -1,960 +1,67 @@ .. This file is part of Invenio Copyright (C) 2014, 2015 CERN. Invenio is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. Invenio is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. .. _git-workflow: -Git -=== - -This page describes the Git collaboration workflow that we try to -follow in our development. - -Introduction ------------- - -Our collaboration model is basically a pull-on-demand model similar to -the one used for the Linux kernel. You may want to read a -`chapter on this collaboration model in the Mercurial book -<http://hgbook.red-bean.com/read/collaborating-with-other-people.html>`_. - -In the recipes below you will encounter several personas with -different roles: - -* Joe Bloggs, head developer and system integrator -* John Doe, developer, maintainer of the *WebFoo* module -* Erika Mustermann, developer, maintainer of the *WebBar* module - - -Setting things up ------------------ - -S1. Setting up your Git identity -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -How to set up your Git identity. - -.. code-block:: console - - $ vim ~/.gitconfig - $ cat ~/.gitconfig - [alias] - k = log --graph --decorate --pretty=oneline --abbrev-commit - [user] - email = john.doe@cern.ch - name = John Doe - [color] - ui = auto - - -Please use the same full name and email address that was used in the -good old CVS !ChangeLog, so that the repo history looks nicely -coherent over time. - -S2. Setting up your private repo -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is how to set up your private repo (on your laptop). - -.. code-block:: console - - $ cd ~/src - $ git clone http://inveniosoftware.org/repo/invenio.git - - -S3. Backuping your private repo (only developers at CERN) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is how to mirror your private repo to the CERN AFS space. - -.. code-block:: console - - $ rsync -rlptDvz -e ssh --delete ~/src/invenio/ \ - johndoe@lxplus.cern.ch:private/src/invenio - - -You should mirror your private repo and your working files from your -laptop to your private AFS space every night or so. This will give -you a safety of having AFS backups around should something bad happen -to your laptop. This is important, because you may have some features -existing only in your personal repo for weeks or months (see below). - -Also, having a mirror of your private repo on AFS will provide you -with an easy way of testing your private uncommitted code on various -other machines, notably CDSDEV. - -S4. Setting up your public repo -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is how to set up your public repo (on your AFS public space). - -.. code-block:: console - - $ ssh johndoe@lxplus.cern.ch # LXPLUS (SLC5) now has git - johndoe@lxplus> mkdir /afs/cern.ch/user/j/johndoe/public/repo - johndoe@lxplus> cd /afs/cern.ch/user/j/johndoe/public/repo - johndoe@lxplus> mkdir invenio-johndoe.git - johndoe@lxplus> cd invenio-johndoe.git - johndoe@lxplus> git --bare init - johndoe@lxplus> chmod a+rx hooks/post-update - johndoe@lxplus> echo "John Doe's personal tree." > description - - -You can now push your private master branch (from your laptop) to your -public repo (on AFS). - -.. code-block:: console - - $ cd ~/src/invenio - $ git push ssh://johndoe@lxplus.cern.ch/~/public/repo/invenio-johndoe.git master - - -You can define a shortcut called ``johndoe-public`` for your public repo -in order to ease future push commands. - -.. code-block:: console - - $ git remote add johndoe-public \ - ssh://johndoe@lxplus.cern.ch/~/public/repo/invenio-johndoe.git - $ git push johndoe-public master - - -S5. Pushing to your public repo from outside CERN -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In order to be able to push to your public repo from outside of CERN -to a specific machine such as cdswaredev that has ssh port hidden -behind the firewall, you should configure your ssh client to connect -to cdswaredev via lxplus proxy gateway, using netcat to forward -traffic to cdswaredev. - -.. code-block:: console - - $ cat ~/.ssh/config - Host lxplus.cern.ch - ProxyCommand ssh lxplus.cern.ch exec /usr/bin/nc %h %p - - -This will enable you to have apparently direct ssh/scp/git command -connection from your laptop to cdsware, as if you were inside CERN. - -Note that this is not needed for regular branch pushing, since LXPLUS -now has git. It is only needed to access git repos on specific -machines, which is rarely the typical developer use case. - -S6. Making your public repo visible on the Web -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Please contact Joe Bloggs in order to make your public repo visible on -Invenio's `repo web interface <http://inveniosoftware.org/repo/>`_. - -S7. Using remote repository locally -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you prefer, you can mount the remote afs filesystem in the local drive, and work -as normal. To accomplish that you need sshfs package installed. - -.. code-block:: console - - $ mkdir ~/afsrepo - $ sshfs -o workaround=rename <username>@lxplus.cern.ch:/afs/cern.ch/user/r/<username>/public/repo \ - ~/afsrepo/ - $ git push ~/afsrepo/invenio.git/ master - - -To unmount the repository. - -.. code-block:: console - - fusermount -u ~/afsrepo - - -You can create aliases or edit /etc/fstab to help you mount the public repository. - -.. code-block:: text - - sshfs#<USERNAME>@lxplus.cern.ch:/afs/cern.ch/user/<LETTER>/<USERNAME>/public/repo fuse user,noauto 0 0 - - -Understanding official repo branches ------------------------------------- - -The official Invenio repository contains several branches for -maintenance and development purposes. We roughly follow the usual git -model as described in -`man 7 gitworkflows <http://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_ -and elsewhere. - -In summary, the new patchlevel releases (X.Y.Z) happen from the ``maint`` -branch, the new minor feature releases (X.Y) happen from the ``master`` -branch, and new major feature releases (X) happen after they mature in the -optional ``next`` branch. A more detailed description follows. - -``maint`` -~~~~~~~~~ - -This is the maintenance branch for the latest stable release. There -can be several maintenance branches for every release series -(**maint-0.99**, **maint-1.0**, **maint-1.1**), but typically we use only -``maint`` for the latest stable release. - -The code that goes to the maintenance branch is of bugfix nature -only. It should not alter DB table schema, Invenio config file -schema, local configurations in the ``etc`` folder or template function -parameters in a backward-incompatible way. If it contains any new -features, then they are switched off in order to be fully compatible -with the previous releases in this series. Therefore, for -installations using any Invenio released X.Y series, it should be -always safe to upgrade the system at any moment in time by (1) backing -up their ``etc`` folder containing local configuration, (2) installing -the corresponding ``maint-X.Y`` branch updates, and (3) rolling back the -``etc`` folder with their customizations. This upgrade process will be -automatized in the future via special ``inveniomanage`` options. - -``master`` -~~~~~~~~~~ - -The ``master`` branch is where the new features are being developed and -where the new feature releases are being made from. The code in -``master`` is reviewed and verified, so that it should be possible to -make a new release out of this branch almost at any given point in -time. However, Invenio installations that would like to track this -branch should be aware that DB table definitions are not frozen and -may change, the config is not frozen and may change, etc, until the -release time. So while ``master`` is relatively stable for usage, it -should be treated with extreme care, because updates between day D1 -and day D2 may require DB schema and ``etc`` configuration changes that -are not covered by usual ``inveniomanage`` update statements, so people -should be prepared to study the differences and update DB schemata and -config files themselves. - -``next (optional)`` -~~~~~~~~~~~~~~~~~~~ - -If a new feature is well implemented, tested and considered stable, it -goes directly into the ``master`` branch described previously. If it is -cleaned, tested and almost stable, but not fully ``master`` worthy yet, -then it may go to the ``next`` branch. The ``next`` branch serves as a -kind of stabilization branch for ``master``. The features may stay in -``next`` for a long enough time to get stabilized, and when they -are ready, they are promoted to ``master`` (or to ``maint`` in some -scenarios). The code in ``next`` may have bugs, may not pass the test -suite, but anyway should be stable enough so that it is almost never -revoked/rebased. - -Usually, ``master`` contains all of ``maint``, and ``next`` contains all of -``master``. This is assured by periodical upward merges -(maint-to-master, master-to-next, etc). - -Working on new features - overview ----------------------------------- - -Here is a schema summarizing how John Doe would work on new features -and fixes and how Joe Bloggs would integrate them. - -.. image:: /_static/invenio-git-workflow.png - :width: 859 - :alt: invenio git workflow with features. - - -The most important thing to recall is that *any topic branch*, be it a -bugfix or a new feature, *should be started off by the developer from the -lowest maint branch it applies to*, -since it will then be merged upwards to all the other branches as part -of the integration process. - -.. image:: /_static/invenio-git-branches.png - :width: 348px - :alt: git tree with maint and master read only branches as well as two - features or bugfix branches. - - -Example: if there is an important bug in v0.99.1 that John is going to -fix, then John should create a topic branch from the tip of -``maint-0.99``, test and everything, and send it over for integration, -and it will then get merged both to ``maint-0.99`` as well as to all the -necessary upwards branches (``maint-1.0``, ``maint-1.1``, ``master``, etc), -as needed, e.g. via periodical ``maint->master`` merges. - -Backporting fixes from ``master`` to ``maint`` should remain exceptional. - -Working on new features - details ---------------------------------- - -W1. Cloning the repo -~~~~~~~~~~~~~~~~~~~~ - -After you clone the official repo (see S2 above), you keep working on -your laptop in your own private git repo, using Atlantis Institute of -Fictive Science setup conditions. - -W2. Working with local topic branches -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You never work on the master branch, you always checkout local *topic -branches* for every feature you are implementing. This will permit -you to switch between topics easily, implement some urgent fixes for -older releases, publish some features while retaining features not -yet ready for public eyes, etc. - -In our workflow example above we created several branches to tackle -several different tasks. - -.. code-block:: console - - $ git checkout master - $ git branch new-feature-a - $ git branch new-feature-b - $ git branch refactor-c - $ git checkout next - $ git branch wild-idea-d - $ git checkout maint - $ git branch bugfix-e - - -The topical branches do not necessarily have to stem from the same -point in the master branch. - -Please name your topical branches sensibly, since their names may -appear in the central repo logs in case of non-trivial merges. -(Please use a dash rather than an underscore in topical branch names.) - -W3. Working on new-feature-b -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You now have some time to work on feature B, so. - -.. code-block:: console - - $ git checkout new-feature-b - [ edit, test, edit, test, commit ] - [ edit, test, edit, test, commit ] - [ more of the same ] - - -until things work as they should for the Atlantis Institute of Fictive -Science demo site. This can take a minute or a few weeks, depending -on the complexity of B. - -While working on B, you can switch to other branches to work on -various more urgent problems, etc. - -W4. Using temporary stash -~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want to switch branches, you have to commit all the -stuff you are currently editing, which may not be what you want. In -that case you can **stash** your commits into a temporary git stash, -switch to a branch, do what you want, and when you come back, replay -the changes from the stash. Here is an example. - -.. code-block:: console - - $ git stash # put local edits to the stash - $ git stash list # list what you have there - stash@`informe 0 <report/0>`_: WIP on foo.py: 2340b5a... WebFoo: new support for baz - $ git checkout refactor-c # work on the refactor-c branch a bit - ... <...> - $ git checkout new-feature-b # come back to the new-feature-b branch - $ git stash apply # replay stuff from stash - $ git diff # verify - - -W5. Testing on DEV servers -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When your new-feature-b code works okay on the demo site, and you -synced it to your /private/ AFS space, you should now test it under -**CDSDEV** or **INSPIREDEV** operating conditions. Some more editing, -testing, and committing may be needed if things are not working as -expected. - -If the code is working properly on CDSDEV in itself, but say some -scalability issues were encountered, then there are two options: (i) -either some more of the editing/testing/committing cycle is needed, or -(ii) the code is considered working fine enough to be merged now, -while the performance issues are savannized to be solved later. - W6. Rebasing against latest git/master ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ At this step the new-feature-b code is working both for Atlantis and for CDS contexts. You should now check the official repo for any updates to catch any changes that may have been committed to origin/master in the meantime. .. code-block:: console $ git checkout master $ git pull You can then **rebase** your new-feature-b branch against recent master. .. code-block:: console $ git checkout new-feature-b $ git rebase master In case of conflicts during the rebase, say in file foo.py, you should resolve them. .. code-block:: console $ vim foo.py $ git add foo.py $ git rebase --continue or you can stop the rebase for good. .. code-block:: console $ git rebase --abort You may prefer rebasing of your local commits rather than merging, so that the project log looks nice. (No ugly empty merge commits, no unnecessary temporary versions.) While rebasing, you may want to squash your commits together, to keep the git repo history clean. See section R4 below for more details. You should test your code once more to verify that it was not broken by the updates. - -W7. Publishing your work -~~~~~~~~~~~~~~~~~~~~~~~~ - -W7.a Pushing into your public repo -++++++++++++++++++++++++++++++++++ - -The new-feature-b code is now ready to be pushed into your -**public repo** for public consumption. Please make sure to check again -that the test cases are working well, and please check once more the -basic code kwalitee, as mentioned in the section R3 below. - -If the test cases work and the code kwalitee is acceptable, push -your branch into your public repo this way: - -.. code-block:: console - - $ git push johndoe-public new-feature-b - - -Then alert Joe Bloggs with a request to review and integrate the -branch, indicating ``git branch johndoe/new-feature-b`` in the email -Subject header so that the emails will be threaded properly and given -special treatment in the haystack of Joe's usual email conversation. -Please also add any special observations for merge. Example: - -.. code-block:: console - - From: john.doe@cern.ch - To: joe.bloggs@cern.ch - Subject: git branch johndoe/new-feature-b - - Hi Joe: - - Please merge git branch johndoe/new-feature-b. Tests added, - kwalitee checked, needed quickly for Jane's forthcoming - new-feature-c. - - Cheers, John Doe - - - -W7.b Sending patches by email -+++++++++++++++++++++++++++++ - -If some occasional code contributors do not have a public repo, they -can generate and **send patches by email** to Joe. Say like this. - -.. code-block:: console - - $ git checkout master - $ git pull - $ git branch foo-fix - $ git checkout foo-fix - $ emacs bar.py - $ git commit -a -m 'WebFoo: fixed bad problem' - $ git format-patch master - $ ls -l 0001-WebFoo-fixed-bad-problem.patch - $ git send-email --to joe.bloggs@cern.ch 0001-WebFoo-fixed-bad-problem.patch - - -Or, instead of the last command, send Joe a normal verbose email with -attached ``0001-WebFoo-fixed-bad-problem.patch`` file. - -W7.c Sending patch-suggestions -++++++++++++++++++++++++++++++ - -As we said in the introduction, John usually maintains the !WebFoo module -while Erika usually maintains the !WebBar module. What happens if Erika -spots a problem some !WebFoo feature? - -If the problem and its solution is clear, Erika can -simply alert John that she's up to it, fix the problem and publish a -branch or send an email to Joe asking for integration. - -If the problem a little bit more complicated or there are several -possible solutions and it is not clear which one is the best or the -solution to the problem requires some deep changes inside the structure -of !WebFoo that may affect other things or the problem requires -optimizations of several pre-existing functions, then it may be best -if Erika contacts John as the !WebFoo module maintainer about the -problem. Maybe John would like to do the changes himself or John can -advise Erika how to go about the problem, etc. - -In the latter case Erika can implement the proposed solution and send -the patch-suggestion email to John as explained in W7.b. John can -than review and approve the change and eventually change what has to be -changed and forward the branch to Joe for integration. - -Note that if such a change to !WebFoo may affect other modules and/or -other APIs, then these have to be usually discussed/reviewed by Joe in -advance, just like other intra-module vs inter-module issues. - -W8. Review process -~~~~~~~~~~~~~~~~~~ - -W8.a Reviewing and merging branches -+++++++++++++++++++++++++++++++++++ - -Joe now starts to **review and integrate** the new-feature-b branch. -This usually takes two rounds: 1) pure reading of the patch can -generate some comments; after the round one is over, 2) testing the -patch can generate other comments. - -If the changes to be done are rather small, then Joe usually does it -himself. - -.. code-block:: console - - $ git log master..johndoe/new-feature-b # even when master is well ahead in future - $ git diff master...johndoe/new-feature-b - $ git merge --log johndoe/new-feature-b - $ git commit --amend # change log message - $ vim Makefile.am # edit to fix something - $ git add Makefile.am - $ git commit --amend -s # commit also this new change and sign-off - $ git push origin-writable master # push to public repo - - -If the changes to be done are rather important, and may reveal a -necessity to make some more amendments to the code, this can eventually -lead to longer edit/test/commit iterations done in -your private repo. If this happens, then, since your code was -already published into a public space (even though as personal only), -you should not rebase anymore (since rebase rewrites history); you -should only merge your new amendments. Or, in case of bigger -rewrites, you can publish a new branch. - -W8.b Reviewing and committing patches -+++++++++++++++++++++++++++++++++++++ - -For patches received by email, a similar review procedure takes -place. To integrate such a patch. - -.. code-block:: console - - $ less ~/0001-Foo.patch - $ emacs ~/0001-Foo.patch # for small edits - $ git am -3 ~/0001-Foo.patch - $ git commit --amend # to change commit message - - -or, for bigger patches that may require more integration work: - -.. code-block:: console - - $ less ~/0001-Foo.patch - $ git am -3 ~/0001-Foo.patch - $ emacs foo.py # change what is needed - $ emacs bar.py # change what is needed - # test, install, etc - $ git add foo.py # add silently Joe's changes to original patch - $ git add bar.py # add silently Joe's changes to original patch - $ git commit --amend # commit everything in John's name - - -Although the last process may be evil at times, since Joe kind of -usurps John's name for the changes, and commits in his name. Hence -this method is usually acceptable only for tiny commits -(e.g. correcting typos). - -W8.c Reviewing and cherry-picking commits -+++++++++++++++++++++++++++++++++++++++++ - -Instead of integrating branches in full, Joe may want to **cherry-pick** -some particular commits or squash branches to keep the project -history clean. An example: - -.. code-block:: console - - $ # see log of a branch: - $ git log erika/cool-stuff - # pick one particular commit: (e.g. some other author in Erika's branch) - $ git cherry-pick 027e1524cd1b823a620620d4b60dd570596fd641 - $ # edit its log message: - $ git commit --amend - $ # squash other commits together while merging: (e.g. other author in Erika's branch) - $ git diff 027e1524cd1b823a620620d4b60dd570596fd641 394d1a2a8488cbd0554f12b627ce478c8d1ee65c > ~/z.patch - $ git apply --check z.patch - $ git apply ~/z.patch --check # test whether patch applies - $ emacs ~/z.patch # edit some lines away, retest until applies - $ git apply --reject z.patch # alternatively, apply only good junks, study rejects later - $ # commit changes as Erika: - $ git commit -a --author='Erika Mustermann <erika.mustermann@cern.ch>' - - -W9. Checking integrated branch -++++++++++++++++++++++++++++++ - -Once all the integration-related iterations are over, and your -new-feature-b code was integrated into the Invenio master branch, -then you fetch it to **check** if it was well integrated, and you delete -your new-feature-b branch since you don't need it anymore. - -.. code-block:: console - - $ git checkout master - $ git pull - $ git diff master..new-feature-b - $ git branch -d new-feature-b - - -If Joe edits something during merge, then the commit SHA1s may not -match, but you would notice and study the differences using diff. - -W10. Deleting integrated branch -+++++++++++++++++++++++++++++++ - -Once new-feature-b is fully merged, you **delete** this branch in your -public repo. - -.. code-block:: console - - $ git push johndoe-public :new-feature-b - - -Remarks often made during code review -------------------------------------- - -R1. Remarks on commit history -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before a topical branch is sent for review and integration, the commit -history of the branch should be checked and eventually polished. Here -is an example. - -Consider a topical branch with history like this. - -.. code-block:: text - - commit1 WebFoo: new xyzzy facility - commit2 WebFoo: fixed typo - commit3 WebFoo: speed-ups for xyzzy daemon - commit4 WebFoo: Python-2.4 compatibility - commit5 WebFoo: Friday weekly cleanup - commit6 WebFoo: even more speed ups - commit7 WebFoo: oops, cleaned documention - commit8 WebFoo: amendments of zyxxy - - -This is not very good. While preserving full commit history in the git -repository would be nice, the problem here is that historical versions -of the xyzzy facility in the topical branch are not always working -properly. The whoops commits are not eliminated. Keeping -intermediary commits does not make sense if they are not working -properly, they would only be making `git bisect` harder in the future. - -Ideally, the individual commits should be in an always-working state -and they should be presented in logical groups. For example the above -branch is better to be squashed as follows: - -.. code-block:: text - - commit1 WebFoo: new xyzzy facility - + commit2 WebFoo: fixed typo - + commit4 WebFoo: Python-2.4 compatibility - + commit7a WebFoo: oops, cleaned documention - commit3 WebFoo: speed-ups for xyzzy daemon - + commit5 WebFoo: Friday weekly cleanup - + commit7b WebFoo: oops, cleaned documention - commit6 WebFoo: even more speed ups - + commit7c WebFoo: oops, cleaned documention - commit8 WebFoo: amendments of zyxxy - - -That is, the initial commit should be without typos and syntax errors, -should be working on Python-2.4 environment already and should -contain respective documentation already. The speed optimisation is -an independent improvement, so this would logically constitute our -second commit. If the commit6 contained documentation bits about -optimisations, the should be presented here. The same is true for the -next even-more-speedups commit. Finally, feature amendments come -last. - -Git has powerful tools to help cleaning topical branches like this. -Notably, you can run `git rebase master -i` to squash/reorder commits, -`git gui` to separate various hunks inside commits, etc. - -Here is an illustration of a typical thinking process during branch -cleanups: - - -* Is the facility fully working now as expected? If it is, keep the - commit. - -* Is this facility or some related one broken in one of the aspects? - If it is, amend and squash. - -* Is this commit an improvement over an already-working facility? If - it is, keep the commit. - -* Is this commit intermediary? Is it worth keeping? Is there a - chance that somebody might want to start off a new branch at this - point in some day? Does this commit helps some future developer to - understand the branch history better? If not, squash. - -* Is the primary author of this commit different? If he is, keep the - commit. Alternatively, squash it, but use `Co-authored-by` commit - log directive. - -* Is the same commit addressing more than one logically separate problem? - If it is, split. - -Having a clean branch history helps in providing sensibly working atomic -updates, helps in understanding commits and code, eases eventual -future bug-hunting via git bisecting, and makes the software generally -more robust. - -R2. Remarks on commit log messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -R2a. Commit message format -++++++++++++++++++++++++++ - -Invenio git commit log messages are usually formatted in the following -way: - -* commit message headline providing short summary (maximum 50 chars) - formatted in the style of ``component: short description``. (using - mostly nouns, no verbs); - -* empty line; - -* commit message body with a detailed description of what this patch does, - formatted as a bulletted list, with one empty line between items (using - present tense). If a given element in the list should appear in the release - notes (to describe changes to Invenio admins and developers) it must be - prefixed with one of the following labels: - -============== =========================================================== -label meaning -============== =========================================================== -NEW commit adds a new feature -SECURITY commit fixes a security issue -FIX commit fixes a bug -BETTER commit improves an existing feature -AMENDS commit invalidates message from different commit identified - by its SHA1 -INCOMPATIBLE compatibility remarks, removing features and dependencies -NOTE any general note (if needed) -============== =========================================================== - - -Here is an example: https://github.com/inveniosoftware/invenio/commit/71df9665bf5fcdd020b67e4cbcedfaddfd6cadaa. - -.. code-block:: text - - WebSearch: field-filtered MARCXML API output - - * Implements field-filtered MARCXML output in Python and Web APIs. - This was working for the TextMARC output, not for MARCXML output. - This commit fixes the problem. Usage: `/record/123?of=xm&ot=100,700` - or `/search?p=ellis&of=xm&ot=100,700`. (closes #1591) - - * Adds new tests for trying to access hidden fields via the - filtered-field API technique. - -Note that if you use ``vim`` or ``emacs git-modes`` to write your commit -messages, you will be alerted about the excessive headline length -(more than 50 characters) via colour syntax highlighting. To use ``vim`` -for example as your commit message editor, add ``export EDITOR=vim`` to -your ``.bashrc``, ``bash_profile`` or variants. - -The short commit logs are easily readable on narrow mobile devices, -are helpful to quickly localise features, and ease any possible -hunting for bugs via git bisecting later, should any trouble arise. - -Here is an example listing the last 15 commits on the master branch. - -.. code-block:: console - - $ git log -n 15 maint-1.1..master --pretty=oneline | grep -v 'Merge b' - c7cd1f184188207b55903e00e78e5b1acbff33c3 BibFormat: author links for mobile app - 6f0641cbde7866adc521793e434f77e2d842f40e WebSearch: display number of hits in mobile output - be86ab82f632c60aea7dfc10677f091104155a86 BibFormat: initial release of mobile app formats - 81dc101b4377951f345b7a174c2f673b672c1c3a BibDocFile: improve BibDoc display in Files tab - d8fd1f23aa63e6c842b3aed9c1509fc1294be719 BibDocFile: raise exception in _build_file_list() - e4a1804b7bbdf61f2b7fe8698684c16aced3f58a BibField: creation date addition and keyword fix - b0e6e6cacfec91393ab1cbfd04ec6dcfdff32dcd BibFormat: new Solr fulltext snippet facility - b98f24bf38b95dd7366d57e8d6d90804957099e5 BibDocFile: additional mimetypes support - 211065f10e1a967e1050b08560e03edca58d9c34 BibField: new fft field in `atlantis.cfg` - e40be7d8af9223483fe63d97f64463d2492fa890 BibRank: increase rnkDOWNLOADS.file_format size - b18ee3fd919c1a06b143761f4611c02f4ac91cab BibField: Python-2.4 compatibility fix - - -See also commit message practices used in the git world, such as -`Git for the lazy: Writing good commit messages -<http://spheredev.org/wiki/Git_for_the_lazy#Writing_good_commit_messages>`_ and -`A Note About Git Commit Messages -<http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_. - -R2b. Commit message QA/review directives -++++++++++++++++++++++++++++++++++++++++ - -The authors can use the following commit signature directives in order -to highlight the quality of the patch at hand before requesting its -review and merge. - -Example: https://github.com/inveniosoftware/invenio/commit/e4a1804b7bbdf61f2b7fe8698684c16aced3f58a - -.. code-block:: text - - BibField: creation date addition and keyword fix - - - * Adds new derived field 'creation_date'. - - - * Fixes keywords defition to always return list. - - Signed-off-by: Jiri Kuncar <jiri.kuncar@cern.ch> - Reviewed-by: Tibor Simko <tibor.simko@cern.ch> - - -Here is the list of QA directives that the author may use: - - ``Reported-by`` - Acknowledges the user who originally reported the bug that this commit - fixes. - - ``Signed-off-by`` - The author says, in essence: "I have carefully implemented the feature - without any leftover to-be-fixed places, I have run all code kwalitee - checks and all relevant unit and functional tests, and everything is good. - To the best of my knowledge, this commit is good to go into the fast merge - track". - - ``Co-authored-by`` - Used when more persons than the current author were involved in creating - the code. This usually happens in peer programming. - - ``Improved-by`` - Acknowledges the person who improved the current code significantly after - the original committer left, say. This differs from review in that the - author provides much more improvements than in a usual review. - -The reviewers then usually add one of the following tags: - - ``Acked-by`` - The reviewer says, in essence: "I have seen this commit from a distance - while walking in the corridor, it looks useful, but I have not had time to - deal with it further". Rarely used. - - ``Tested-by`` - The reviewer says, in essence: "In addition, I have paged through the code, - tested its kwalitee, tested the desired functionality that this commit - implements, and all is well." - - ``Reviewed-by`` - The reviewer says, in essence: "In addition, I have read every line of the - source code in detail." - -Note that a similar system is used in the git world, e.g. Linux kernel -`https://www.kernel.org/doc/Documentation/SubmittingPatches <https://www.kernel.org/doc/Documentation/SubmittingPatches>`_ or Git -itself -`http://git.kernel.org/cgit/git/git.git/plain/Documentation/SubmittingPatches <http://git.kernel.org/cgit/git/git.git/plain/Documentation/SubmittingPatches>`_. -While we use some tags in similar context, we use some other tags -slightly differently. - -R3. Remarks on the coding -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Here is a small sample of often-made code remarks: - - -* Compliance to our `coding standards <http://invenio-demo.cern.ch/help/hacking/coding-style>`_. Stick to PEP 8, run ``pylint`` often. -* Missing `test cases <http://invenio-demo.cern.ch/help/hacking/test-suite>`_. -* Sanitisation of input variables. Default value check, XSS. -* Proper escaping of HTML output. Use ``cgi.escape()``. -* Proper ``run_sql()`` argument quoting. SQL injection. -* Compliance to Python 2.3. Test on SLC4. - -Ideally you should make sure they are not present in your public -branches before asking for merge into the git/master. You can do a -**code kwalitee** check yourself by running. - -.. code-block:: console - - $ cd src/invenio/modules/bibedit/lib - ... hack on bibrecord_engine.py and friends - ... make install etc until satisfaction - $ python ../../miscutil/lib/kwalitee.py --check-all ./bibrecord*.py - - -and then follow the output recommendations. (If =--check-all= is too -troublesome to implement e.g. due to bad legacy code, then please fix -at least the recommendations produced by running =--check-some=.) - -For more information on the code kwalitee checking, on the -above-listed problems and on ways to solve them, as well as some -other frequently made remarks on the coding, please see the dedicated -InvenioQualityAssurances wiki page. - -R4. Notes on the review process timeline -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Our pull-on-demand collaboration model enables us to have a *clean* -development version of Invenio - there are no problems anymore with -the CVS HEAD being broken because people were committing things before -checking etc. - -The price we pay for the inherent review process in the pull-on-demand -collaboration model is a certain time delay before the code becomes -published and visible. It is normal for John and Erika to have many -branches sitting around, waiting for Joe to integrate them. The -integration delay can vary depending on the complexity of the branch. - -E.g. it helps to check in advance the list of frequent remarks -mentioned in the section R3 above. - -E.g. it helps to provide test cases for every bigger commit. -(Especially for deep changes that may affect a lot of the codebase, not -mentioning changes affecting inter-module relationships.) - -E.g. it does not help if a branch combines several different features -together. We should not mix feature A and feature B together in the -same commit and/or branch that implements some new feature C. It is -always better to separate different features into different topical -branches. On the other hand, it may not be good to separate too much, -if features A and B are clearly logically linked. The common sense -will tell how much separation is needed. (Similarly to how the common -sense says when to stop the database design normalization process.) diff --git a/docs/developersguide/python.rst b/docs/developersguide/python.rst index b3eac17b1..ace87f46c 100644 --- a/docs/developersguide/python.rst +++ b/docs/developersguide/python.rst @@ -1,59 +1,47 @@ .. This file is part of Invenio Copyright (C) 2014, 2015 CERN. Invenio is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. Invenio is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. -Python -====== - -Coding standards ----------------- - -We follow `PEP-8 <https://www.python.org/dev/peps/pep-0008/>`_ and `PEP-257 -<https://www.python.org/dev/peps/pep-0257/>`_ and sort imports via ``isort``. -Please plug corresponding checkers such as ``flake8`` to your code editor. - -Coding principles ------------------ - -We adopt the following principles: - -- *Convention over Configuration* means that common building blocks - are provided for you, so use them! If you are not sure or documentation - of certain feature is missing, contact the developers. - -- *Don't Repeat Yourself (DRY)* to help us keep our software maintainable. - Duplication of code fragments makes application codebase larger and more - importantly it can become a source of many errors during future development - (refactoring). - -- *Agile Development* where each iteration should lead to working code in - relatively short time while incremental steps are small and easy to understand - by other developers. When you are done with editing do not forget to run the - tests to make sure that all other modules are working fine. +Learning Python +=============== Anti-patterns ------------- Learn to recognise and avoid Python `anti-patterns <http://docs.quantifiedcode.com/python-anti-patterns/index.html>`_. +3. **Contributing code?** + + i. Read `The Zen of Python <https://en.wikipedia.org/wiki/Zen_of_Python>`_. + + ii. Read `Python Anti-Patterns + <http://docs.quantifiedcode.com/python-anti-patterns/>`_. + iii. Code with style. Plug `pycodestyle + <https://pypi.python.org/pypi/pycodestyle>`_ (`PEP-8 + <https://www.python.org/dev/peps/pep-0008/>`_), `pydocstyle + <https://pypi.python.org/pypi/pydocstyle>`_ (`PEP-257 + <https://www.python.org/dev/peps/pep-0257/>`_), `Flake8 + <https://pypi.python.org/pypi/flake8>`_, `ISort + <https://pypi.python.org/pypi/isort>`_ tools into your editor. + + Entry points ------------ We use Python `entry_points`_ as a way to provide extensions for packages. .. _entry_points: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points - diff --git a/docs/index.rst b/docs/index.rst index b2291be9b..b899a441c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,103 +1,111 @@ .. This file is part of Invenio. Copyright (C) 2014, 2015 CERN. Invenio is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. Invenio is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Invenio; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. In applying this license, CERN does not waive the privileges and immunities granted to it by virtue of its status as an Intergovernmental Organization or submit itself to any jurisdiction. .. include:: ../README.rst +.. _overview: + Overview -------- .. toctree:: :maxdepth: 2 introduction/index introduction/digitalrepositories introduction/usecases introduction/history +.. _users-guide: + User's Guide ------------ This part of the documentation will show you how to get started using Invenio. .. toctree:: :maxdepth: 2 usersguide/quickstart usersguide/tutorial/index usersguide/running usersguide/loading usersguide/accessing usersguide/orcid-login usersguide/migrating +.. _deployment-guide: + Deployment Guide ---------------- This part of the documentation will show you how to setup a production system for running Invenio. .. toctree:: :maxdepth: 2 deploymentguide/overview deploymentguide/services deploymentguide/configuring deploymentguide/daemons deploymentguide/monitoring deploymentguide/highavailability deploymentguide/fabric deploymentguide/docker +.. _developers-guide: Developer's Guide ----------------- This part of the documentation will show you how to get started developing for Inveno. .. toctree:: :maxdepth: 2 developersguide/tutorial/index developersguide/development-environment developersguide/architecture developersguide/entrypoints developersguide/invenio-modules developersguide/create-a-datamodel Community --------- Notes on getting involved, contributing, legal information and release notes are here for the interested. .. toctree:: :maxdepth: 2 - community/getting-involved - community/code-of-conduct - community/translation-guide + community/getting-help + community/channels community/contribution-guide community/style-guide + community/translation-guide community/maintainers-guide/index.rst community/releases + community/code-of-conduct community/license community/authors todo diff --git a/docs/processes/developing.rst b/docs/processes/developing.rst deleted file mode 100644 index d0d00ead1..000000000 --- a/docs/processes/developing.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015, 2016 CERN. - - Invenio is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of the - License, or (at your option) any later version. - - Invenio is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -============ - Developing -============ - -:: - - Mutable defaults - The Master - Is full of regrets - —-after Yosa Buson (1716-1784) - -Developing principles -===================== - -.. _contributing-documentation: - -1. **Contributing documentation?** ReST and Sphinx. Contribute as code. - -.. _contributing-i18n-translations: - -2. **Contributing I18N translations?** GNU gettext. See :ref:`i18n`. - -.. _contributing-code: - -3. **Contributing code?** - - i. Read `The Zen of Python <https://en.wikipedia.org/wiki/Zen_of_Python>`_. - - ii. Read `Python Anti-Patterns - <http://docs.quantifiedcode.com/python-anti-patterns/>`_. - iii. Code with style. Plug `pycodestyle - <https://pypi.python.org/pypi/pycodestyle>`_ (`PEP-8 - <https://www.python.org/dev/peps/pep-0008/>`_), `pydocstyle - <https://pypi.python.org/pypi/pydocstyle>`_ (`PEP-257 - <https://www.python.org/dev/peps/pep-0257/>`_), `Flake8 - <https://pypi.python.org/pypi/flake8>`_, `ISort - <https://pypi.python.org/pypi/isort>`_ tools into your editor. - - - iv. Use sensible commit history. (See below.) - - v. Run kwalitee checks locally. - - - ``kwalitee check message master..my-feature-branch`` - - ``kwalitee check files master..my-feature-branch`` - - ``kwalitee check authors master..my-feature-branch`` - - ``kwalitee prepare release master..my-feature-branch`` - - vi. Follow egoless programming principles. See :ref:`code-of-conduct`. - - vii. Read the following contributing guide and developer guidelines. - -.. _contributing-guide: - -Contributing guide -================== - -.. include:: ../../CONTRIBUTING.rst - :start-after: and welcome! diff --git a/docs/processes/index.rst b/docs/processes/index.rst deleted file mode 100644 index d59812500..000000000 --- a/docs/processes/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015, 2016 CERN. - - Invenio is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of the - License, or (at your option) any later version. - - Invenio is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -========= -Processes -========= - -.. toctree:: - :maxdepth: 2 - - reporting - triaging - sprinting - developing - reviewing - integrating - releasing diff --git a/docs/processes/releasing.rst b/docs/processes/releasing.rst deleted file mode 100644 index 3300a3ccc..000000000 --- a/docs/processes/releasing.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015, 2016 CERN. - - Invenio is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of the - License, or (at your option) any later version. - - Invenio is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -=========== - Releasing -=========== - -:: - - The old repository - A tag jumps in - Plop - —-after Matsuo Basho (1644-1694) - -Releasing principles -==================== - -.. _cross-check-ci-green-lights: - -1. **Cross-check CI green lights.** Are all Travis builds green? Is nightly - Jenkins build green? - -.. _cross-check-read-the-docs-documentation-builds: - -2. **Cross-check Read The Docs documentation builds.** Are docs building fine? - Is this check done as part of the continuous integration? If not, add it. - -.. _cross-check-demo-site-builds: - -3. **Cross-check demo site builds.** Is demo site working? - -.. _check-manifest: - -4. **check-manifest** Are all files included in the release? Is this check done - as part of the continuous integration? If not, add it. - -.. _check-author-list: - -5. **Check author list.** Are all committers listed in AUTHORS file? Use - ``kwalitee check authors``. Add newcomers. Is this check done as part of the - continuous integration? If not, add it. - -.. _update-i18n-message-catalogs: - -6. **Update I18N message catalogs.** - -.. _update_version_number: - -7. **Update version number.** Stick to `semantic versioning - <http://semver.org/>`_. - -.. _generate-release-notes: - -8. **Generate release notes.** Use `kwalitee prepare release v1.1.0..` to - generate release notes. Use empty commits with "AMENDS" to amend wrong past - messages before releasing. - -.. _push-pre-release-to-testpypi: - -9. **Push a pre-release to testpypi.** Try a test install from there. - -.. _tag-it-push-it-: - -10. **Tag it. Push it.** Sign the tag with your GnuPG key. Push it to PyPI. Is - the PyPI deployment done automatically as part of the continuous - integration? If not, add it. - -.. _bump-it: - -11. **Bump it.** Don't forget the issue the pull request with a post-release - version bump. Use ``.devYYYYMMDD`` suffix. - -.. _add-release-notes-on-github-tweet-it-post-it: - -12. **Add release notes on GitHub. Tweet it. Post it.** Make publicity for - production-ready releases. This is not automated yet. - -.. _structured-release-notes: - -Structured release notes -======================== - -The release notes are prepared from the commit log messages that should include -the following labels: - -+--------------+--------------------------+ -| commit label | release notes section | -+==============+==========================+ -| SECURITY | Security fixes | -+--------------+--------------------------+ -| INCOMPATIBLE | Incompatible changes | -+--------------+--------------------------+ -| NEW | New features | -+--------------+--------------------------+ -| BETTER | Improved features | -+--------------+--------------------------+ -| FIX | Bug fixes | -+--------------+--------------------------+ -| NOTE | Notes | -+--------------+--------------------------+ -| (AMENDS) | (amending past messages) | -+--------------+--------------------------+ -| (missing) | (developers only) | -+--------------+--------------------------+ - -For more, see `kwalitee <http://kwalitee.readthedocs.io/>`_. diff --git a/docs/processes/reporting.rst b/docs/processes/reporting.rst deleted file mode 100644 index 51549ad6f..000000000 --- a/docs/processes/reporting.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015, 2016 CERN. - - Invenio is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of the - License, or (at your option) any later version. - - Invenio is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -========= -Reporting -========= - -:: - - An issue in the morning - A feature request in the evening - What else? - --after Ekon - -Reporting principles -==================== - -Have you encountered a bug or do you have a new feature request? Here are a few -tips on our issue reporting practices. - -.. _if-it-aint-on-github-it-does-not-exist: - -1. **If it ain’t on GitHub, it does not exist.** Please document every bug or - every feature request on GitHub in respected repositories. - -.. _found-security-issue-alert-use-privately: - -2. **Found security issue? Alert us privately.** If you find a security issue - that has a possible dangerous exploit, please alert us privately at - ``<info@inveniosoftware.org>``. This will allow us to distribute a security - patch before potential attackers look at the issue. - -.. _check-existing-issues-before-submitting: - -3. **Check existing issues before submitting.** Please check opened or closed - issued before submitting. Somebody else might have had the same issue as you. - -.. _describe-concrete-steps-how-to-reproduce-a-problem: - -4. **Describe concrete steps how to reproduce a problem.** Which version you - used? What you did? What was the outcome? What you expected instead? - -.. _submit-a-use-case-submit-a-test-case-code: - -5. **Submit a use case. Submit a test case code.** Please clarify the use case - in mind with as much explicit detail as necessary. Other Invenio instances - may have different implicit assumptions than you. - -.. _get-involved-comment-ad-advise-on-other-issues: - -6. **Get involved! Comment and advise on other issues.** Help the community and - see your responsibilites widen. - -.. _join-invenio-chat-room: - -7. **Join Invenio chat room.** Sometimes a quick chat may be better than long - GitHub issue. - -.. _watch-notifications-in-interested-repositories: - -9. **Watch notifications in interested repositories.** Subscribe to GitHub - notifications to stay up-to-date on what is going on. diff --git a/docs/processes/reviewing.rst b/docs/processes/reviewing.rst deleted file mode 100644 index df4191fbb..000000000 --- a/docs/processes/reviewing.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015, 2016 CERN. - - Invenio is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of the - License, or (at your option) any later version. - - Invenio is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -=========== - Reviewing -=========== - -:: - - Ecce pull request! - Undocumented features - Still shivering - —-after Akutagawa Ryunosuke (1892-1927) - -Reviewing principles -==================== - -.. _every-pr-should-preserve-or-increase-code-coverage: - -1. **Every PR should preserve or increase code coverage.** If it ain’t green, it - ain’t finished. - -.. _check-it-as-a-black-box: - -2. **Check it as a black box.** Check the overall picture of input, "something - happens", output chain. If it ain’t documented, it ain’t finished. - -.. _check-it-as-a-white-box: - -3. **Check it as a white box.** Check implementation details of - "something-happens". If it ain’t styled, it ain’t finished. - -.. _check-it-as-a-release-news: - -4. **Check it as a release news.** Check commit messages. Are they - understandable? Do they use FIX or BETTER labels? If a commit does not - announce anything, it may not be finished. See - :ref:`structured-release-notes`. diff --git a/docs/processes/sprinting.rst b/docs/processes/sprinting.rst deleted file mode 100644 index 4a693b3f1..000000000 --- a/docs/processes/sprinting.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. This file is part of Invenio - Copyright (C) 2015, 2016 CERN. - - Invenio is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of the - License, or (at your option) any later version. - - Invenio is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with Invenio; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - -=========== - Sprinting -=========== - -:: - - Ah, unfinished issues! - All that remains - Of the Scrum Master dreams. - —-after Matsuo Basho (1644-1694) - -Sprinting principles -==================== - -.. _before-planning-sprint-do-your-homework: - -1. **Before planning a sprint, do your homework.** Start by drafting initial - thoughts about high-level requirements and use cases in an RFC. Be specific. - - i. About - ii. Use cases - iii. Mock-up screenshots - iv. High-level architecture - v. High-level API - -.. _discuss-with-various-invenio-services-and-experts: - -2. **Discuss with various Invenio services and experts.** Check for other - similar use cases and synergies. Use the community. Seek expert opinions. - -.. _establish-a-cross-service-team: - -3. **Establish a cross-service team.** "Alone we can do so little; together we - can do so much." --Helen Keller - -.. _start-with-a-kick-off-meeting: - -4. **Start with a kick-off meeting.** Invite all sprint team members to kick off - the sprint and plan its details collectively. Invite related technology - experts to provide input to estimated tasks. Invite related service managers - to help making sure the use cases were well understood. - -.. _establish-a-backlog-of-tasks: - -5. **Establish a backlog of tasks.** List everything that needs to be done. Keep - it short. Use GitHub "Sprint-Foo" labels or milestones. - -.. _keep-it-manageable: - -6. **Keep it manageable.** Plan no more than a two-week sprint. Break up longer - sprints into manageable two-week chunks. Beware of attention span. - Prioritise. - -.. _act: - -7. **Act.** Trying our best to finish all tasks in time? "No. Try not. Do. Or do - not. There is no try." (--Master Yoda) - -.. _hold-very-short-daily-stand-up-meetings: - -8. **Hold very short daily stand-up meetings.** What has everyone done since - yesterday? Is anyone blocked by anything? What is everyone going to do next? - -.. _once-over-review-achievements: - -9. **Once over, review achievements.** Did everything go as planned? Were you - too optimistic or too pessimistic regarding backlog and time planning? What - have we learned? - -.. _finish-by-releasing-packages-and-deploying-features: - -10. **Finish by releasing packages and deploying features.** Close sprints by - releasing the software and deploying the features on concerned services --- - production or sandbox.