Mercurial Repository: p/roundup/code: doc/developers.txt comparison

comparison doc/developers.txt @ 7109:561c66232347

Merge

author	Ralf Schlatterbeck <rsc@runtux.com>
date	Thu, 08 Dec 2022 11:18:46 +0100
parents	e4e651b1bcfa
children	d0ef168a9379

comparison

equal deleted inserted replaced

-:b26207712c2b
+:561c66232347
 Developing Roundup
 ==================
 .. note::
 The intended audience of this document is the developers of the core
-Roundup code. If you just wish to alter some behaviour of your Roundup
+Roundup code. If you just wish to alter some behavior of your Roundup
-installation, see `customising roundup`_.
+installation, see `Customising Roundup`_.
 Contents
 .. contents::
 :local:
-If you are looking for info on managing the roundup-tracker.org
-infrastructure, that information has migrated to website/README.txt
-in the roundup repo.
 Getting Started
 ---------------
-Anyone wishing to help in the development of Roundup must read `Roundup's
+If you are looking for a good first issue, search for `StarterTicket
-Design Document`_ and the `implementation notes`_.
+on https://issues.Roundup-tracker.org`_. These include issues where
+Python development, Documentation or Web design skills are useful.
+You can continue the conversation using the issue or join the
+Roundup-devel list to get assistance and verify your planned changes.
 All development is coordinated through two resources:
-- roundup-devel mailing list at
+- Roundup-devel mailing list at
-https://sourceforge.net/projects/roundup/lists/roundup-devel
+https://sourceforge.net/projects/Roundup/lists/Roundup-devel
 - The issue tracker running at
-https://issues.roundup-tracker.org/
+https://issues.Roundup-tracker.org/
+In addition, the Roundup IRC channel on irc.oftc.net can be accessed
+via the web interface shown on the Contact page. The channel is logged
+and the web sites for the logs are shown in the channel topic. You can
+ask questions and use it to coordinate work discussed using the
+resources above.
+Anyone wishing to help in the development of the Roundup Python core
+may find `Roundup's Design Document`_ and the `implementation notes`_
+helpful.
+People working on Documentation or designing changes to the Web
+interface don't need to get into the implementation internals.
 Small Changes
 -------------
 Most small changes can be submitted as patches through the
-`issue tracker`_ or sent to `roundup-devel mailing list`_.
+`issue tracker`_ or sent to `Roundup-devel mailing list`_.
-Source Repository Access
-------------------------
-See https://www.roundup-tracker.org/code.html.
-For all other questions ask on the development mailinglist.
 Project Rules
 -------------
-Mostly the project follows Guido's Style (though naming tends to be a little
+Be polite to others. There is no place for ad hominem attacks.
-relaxed sometimes). In short:
+Mostly the project follows Guido's Python Style (though naming tends
+to be a little relaxed sometimes). In short:
 - 80 column width code
 - 4-space indentations
-- All modules must have an Id line near the top
 Other project rules:
-- New functionality must be documented, even briefly (so at least we know
+- new functionality must be documented, even briefly (so at
-where there's missing documentation) and changes to tracker configuration
+least we know where there's missing documentation) and
-must be logged in the upgrading document.
+changes to tracker configuration must be logged in the
-- subscribe to roundup-checkins to receive checkin notifications from the
+upgrading document.
-other developers with write access to the source-code repository.
+- discuss any changes with the other developers on
-- discuss any changes with the other developers on roundup-dev. If nothing
+Roundup-dev. If nothing else, this makes sure there's no
-else, this makes sure there's no rude shocks
+rude shocks.
-- write unit tests for changes you make (where possible), and ensure that
+- write unit tests for changes you make (where possible),
-all unit tests run before committing changes
+and ensure that all unit tests run before committing
-- run pychecker over changed code
+changes.
+- run flake8_ or pylint_ over changed code.
+- if you have direct commit access to the repository,
+subscribe to Roundup-checkins to receive checkin
+notifications from the other developers with write access
+to the source-code repository.
+The goal is to have no flake8 issues. Current code does include long
+lines and use of mutable objects in function signatures. Some third
+party code (e.g. ZPT) vendored into the codebase has more issues.
 The administrators of the project reserve the right to boot developers who
 consistently check in code which is either broken or takes the codebase in
 directions that have not been agreed to.
+Source Repository Access
+------------------------
+Roundup is developed using the `Mercurial distributed version control
+system (DVCS)`_ [1]_. It is `hosted at Sourceforge`_. See
+https://www.Roundup-tracker.org/code.html for details.
+For all other questions ask on the development mailing list.
+Other Resources - CI, Code Coverage
+-----------------------------------
+Roundup has a `copy of the mercurial repository on GitHub`_. It is
+updated manually after every few commits to the Mercurial
+repository. Updates trigger the CI pipeline which happens on two
+services:
+1. `GitHub Actions`_. It runs Docker container scans using Anchore as
+well as security scans for dependencies using CodeQL. Also it
+runs the test suite on multiple versions of Python.
+2. `TravisCI`_ is also used to run CI. It runs the test suite on
+multiple Python versions. It also provides alpha and development
+Python releases faster than GitHub.
+GitHub actions upload coverage statistics to both `CodeCov`_ and
+`Coveralls`_. TravisCI only uploads to CodeCov.
+We run our own issue tracker so we can dogfood the code. So we do not
+use GitHub issues. Pull requests are grudgingly accepted. They have to
+be exported and applied to the Mercurial repository. This is time
+consuming so patches attached to the issue are preferred.
 Debugging Aids
 --------------
 See :doc:`debugging <debugging>`.
 GNU gettext package
 ~~~~~~~~~~~~~~~~~~~
 This chapter is full of references to GNU `gettext package`_.
 GNU gettext is a "must have" for nearly all steps of internationalizing
-any program, and it's manual is definetely a recommended reading
+any program, and it's manual is definitely a recommended reading
 for people involved in `I18N`_.
 There are GNU gettext ports to all major OS platforms.
 Windows binaries are available from `GNU mirror sites`_.
 <button name="btn_wink" value=" Wink " i18n:attributes="value" />
 will translate the caption (and return value) for the "wink" button.
 * explicit msgids.  Sometimes it may be useful to specify msgid
-for the element translation explicitely, like this::
+for the element translation explicitly, like this::
 <span i18n:translate="know what i mean?">this text is ignored</span>
 When rendered, element contents will be replaced by translation
 of the string specified in ``i18n:translate`` attribute.
 Translatable Messages`_.)
 At run time, Roundup automatically compiles message catalogs whenever
 `PO`_ file is changed.
+.. [1] Roundup is written in Python and we believe in using tools in
+the Python ecosystem whenever possible.
 .. _`Customising Roundup`: customizing.html
 .. _`Roundup's Design Document`: spec.html
 .. _`implementation notes`: implementation.html
 .. _External hyperlink targets:
 .. _alexander smishlajev:
 .. _als: https://sourceforge.net/u/a1s/profile/
+.. _CodeCov: https://app.codecov.io/gh/roundup-tracker/roundup
+.. _copy of the mercurial repository on GitHub:
+https://github.com/roundup-tracker/roundup
+.. _Coveralls: https://coveralls.io/github/roundup-tracker/roundup
 .. _cygwin: https://www.cygwin.com/
 .. _emacs: https://www.gnu.org/software/emacs/
-.. _gettext package: http://www.gnu.org/savannah-checkouts/gnu/gettext/manual/gettext.html
+.. _flake8: https://flake8.pycqa.org/en/latest/
+.. _gettext package: https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/gettext.html
 .. _gettext module: https://docs.python.org/2/library/gettext.html
-.. _GNU: http://www.gnu.org/
+.. _GitHub Actions: https://github.com/roundup-tracker/roundup/actions
-.. _GNU mirror sites: http://www.gnu.org/prep/ftp.html
+.. _GNU: https://www.gnu.org/
+.. _GNU mirror sites: https://www.gnu.org/prep/ftp.html
+.. _hosted at sourceforge:
+https://sourceforge.net/p/roundup/code/ci/default/tree/
 .. _issue tracker: https://issues.roundup-tracker.org/
 .. _Lokalize: https://apps.kde.org/lokalize/
 .. _KDE: https://kde.org/
 .. _linux: https://www.linux.org/
+.. _Mercurial distributed version control system (DVCS):
+https://www.mercurial-scm.org/
 .. _Plural Forms:
-http://www.gnu.org/savannah-checkouts/gnu/gettext/manual/gettext.html
+https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/gettext.html
 .. _po filetype plugin:
 https://vim.sourceforge.io/scripts/script.php?script_id=695
 .. _PO utilities: https://github.com/pinard/po-utils
 .. _poEdit: https://poedit.net/
+.. _pylint: https://pylint.pycqa.org/en/latest/
 .. _Roundup Source:
 .. _Roundup source distribution:
 .. _Roundup binary distribution:
 https://sourceforge.net/projects/roundup/files/
 .. _roundup-devel mailing list:
 https://sourceforge.net/projects/roundup/lists/roundup-devel
+.. _StarterTicket on https://issues.roundup-tracker.org:
+https://issues.roundup-tracker.org/issue?@columns=title,id,activity,status&@sort=activity&@filter=status,keywords&status=-1,1,2&keywords=15&@dispname=Starter%20tickets
 .. _TAL:
 .. _Template Attribute Language:
 https://pagetemplates.readthedocs.io/en/latest/history/TALSpecification14.html
 .. _TALES:
 .. _Template Attribute Language Expression Syntax:
 https://pagetemplates.readthedocs.io/en/latest/history/TALESSpecification13.html
+.. _TravisCI: https://app.travis-ci.com/github/roundup-tracker/roundup
 .. _vim: https://www.vim.org/
 .. _ZPTInternationalization: http://grok.zope.org/documentation/how-to/how-to-internationalize-your-application/view

Mercurial > p > roundup > code

comparison doc/developers.txt @ 7109:561c66232347