matthias/mayan-edms
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Restructure the development chapter

Browse Source 
Signed-off-by: Roberto Rosario <roberto.rosario@mayan-edms.com>
This commit is contained in:
Roberto Rosario
2019-11-30 16:59:59 -04:00
parent 242330ebaf
commit 22d6164781
12 changed files with 30 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
docs/chapters/development/caa_entity.txt Normal file
View File

@@ -0,0 +1,247 @@
==================================================
Mayan EDMS Entity Contributor Assignment Agreement
==================================================
Thank you for your interest in contributing to Mayan EDMS ("We" or "Us").
This contributor agreement ("Agreement") documents the rights granted by
contributors to Us. To make this document effective, please print it, sign it
(by copyright holder or authorized party) and send it to Us by email to
caa@mayan-edms.com. This is a legally binding document, so please read it
carefully before agreeing to it. The Agreement may cover more than one
software project managed by Us.
1. Definitions
==============
"You" means any Legal Entity on behalf of whom a Contribution has been received
by Us. "Legal Entity" means an entity which is not a natural person.
"Affiliates" means other Legal Entities that control, are controlled by, or
under common control with that Legal Entity. For the purposes of this
definition, "control" means (i) the power, direct or indirect, to cause the
direction or management of such Legal Entity, whether by contract or otherwise,
(ii) ownership of fifty percent (50%) or more of the outstanding shares or
securities which vote to elect the management or other persons who direct such
Legal Entity or (iii) beneficial ownership of such entity.
"Contribution" means any work of authorship that is Submitted by You to Us in
which You own or assert ownership of the Copyright. We cannot accept
contributions for which you do not own the Copyright or for which you don't
have the necessary legal power to transfer.
"Copyright" means all rights protecting works of authorship owned or controlled
by You or Your Affiliates, including copyright, moral and neighboring rights,
as appropriate, for the full term of their existence including any extensions
by You.
"Material" means the work of authorship which is made available by Us to third
parties. When this Agreement covers more than one software project, the
Material means the work of authorship to which the Contribution was Submitted.
After You Submit the Contribution, it may be included in the Material.
"Submit" means any form of electronic, verbal, or written communication sent
to Us or our representatives, including but not limited to electronic mailing
lists, source code control systems, and issue tracking systems that are managed
by, or on behalf of, Us for the purpose of discussing and improving the
Material, but excluding communication that is conspicuously marked or otherwise
designated in writing by You as "Not a Contribution."
"Submission Date" means the date on which You Submit a Contribution to Us.
"Effective Date" means the date You execute this Agreement or the date You
first Submit a Contribution to Us, whichever is earlier.
2. Grant of Rights
==================
2.1 Copyright Assignment
------------------------
a. At the time the Contribution is Submitted, You assign to Us all right, title,
and interest worldwide in all Copyright covering the Contribution; provided
that this transfer is conditioned upon compliance with Section 2.3.
b. To the extent that any of the rights in Section 2.1(a) cannot be assigned by
You to Us, You grant to Us a perpetual, worldwide, exclusive, royalty-free,
transferable, irrevocable license under such non-assigned rights, with rights
to sublicense through multiple tiers of sublicensees, to practice such
non-assigned rights, including, but not limited to, the right to reproduce,
modify, display, perform and distribute the Contribution; provided that this
license is conditioned upon compliance with Section 2.3.
c. To the extent that any of the rights in Section 2.1(a) can neither be
assigned nor licensed by You to Us, You irrevocably waive and agree never to
assert such rights against Us, any of our successors in interest, or any of
our licensees, either direct or indirect; provided that this agreement not
to assert is conditioned upon compliance with Section 2.3.
d. Upon such transfer of rights to Us, the Contribution will be licenses under
the terms of the Material.
2.2 Patent License
------------------
For patent claims including, without limitation, method, process, and apparatus
claims which You or Your Affiliates own, control or have the right to grant,
now or in the future, You grant to Us a perpetual, worldwide, non-exclusive,
transferable, royalty-free, irrevocable patent license, with the right to
sublicense these rights to multiple tiers of sublicensees, to make, have made,
use, sell, offer for sale, import and otherwise transfer the Contribution and
the Contribution in combination with the Material (and portions of such
combination). This license is granted only to the extent that the exercise of
the licensed rights infringes such patent claims; and provided that this license
is conditioned upon compliance with Section 2.3.
2.3 Outbound License
--------------------
As a condition on the grant of rights in Sections 2.1 and 2.2, We agree to
license the Contribution only under the terms of the license or licenses which
We are using on the Submission Date for the Material (including any rights to
adopt any future version of a license if permitted).
2.4 Moral Rights
----------------
If moral rights apply to the Contribution, to the maximum extent permitted by
law, You waive and agree not to assert such moral rights against Us or our
successors in interest, or any of our licensees, either direct or indirect.
2.5 Our Rights
--------------
You acknowledge that We are not obligated to use Your Contribution as part of
the Material and may decide to include any Contribution We consider appropriate.
2.6 Reservation of Rights
-------------------------
Any rights not expressly assigned or licensed under this section are expressly
reserved by You.
3. Agreement
============
You confirm that:
a. You have the legal authority to enter into this Agreement.
b. You or Your Affiliates own the Copyright and patent claims covering the
Contribution which are required to grant the rights under Section 2.
c. The grant of rights under Section 2 does not violate any grant of rights
which You or Your Affiliates have made to third parties.
4. Disclaimer
=============
EXCEPT FOR THE EXPRESS WARRANTIES IN SECTION 3, THE CONTRIBUTION IS PROVIDED
"AS IS". MORE PARTICULARLY, ALL EXPRESS OR IMPLIED WARRANTIES INCLUDING,
WITHOUT LIMITATION, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY DISCLAIMED BY YOU TO US
AND BY US TO YOU. TO THE EXTENT THAT ANY SUCH WARRANTIES CANNOT BE DISCLAIMED,
SUCH WARRANTY IS LIMITED IN DURATION TO THE MINIMUM PERIOD PERMITTED BY LAW.
5. Consequential Damage Waiver
==============================
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL YOU OR US
BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF ANTICIPATED SAVINGS, LOSS OF DATA,
INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL AND EXEMPLARY DAMAGES ARISING OUT
OF THIS AGREEMENT REGARDLESS OF THE LEGAL OR EQUITABLE THEORY (CONTRACT, TORT
OR OTHERWISE) UPON WHICH THE CLAIM IS BASED.
6. Miscellaneous
================
6.1 Jurisdiction
----------------
This Agreement will be governed by and construed in accordance with the laws of
Puerto Rico excluding its conflicts of law provisions. Under certain circumstances,
the governing law in this section might be superseded by the United Nations
Convention on Contracts for the International Sale of Goods ("UN Convention")
and the parties intend to avoid the application of the UN Convention to this
Agreement and, thus, exclude the application of the UN Convention in its
entirety to this Agreement.
6.2 Acceptance
--------------
This Agreement sets out the entire agreement between You and Us for Your
Contributions to Us and overrides all other agreements or understandings.
6.3 Third parties
-----------------
If You or We assign the rights or obligations received through this Agreement
to a third party, as a condition of the assignment, that third party must
agree in writing to abide by all the rights and obligations in the Agreement.
6.4 Unmet responsibilities
--------------------------
The failure of either party to require performance by the other party of any
provision of this Agreement in one situation shall not affect the right of a
party to require such performance at any time in the future. A waiver of
performance under a provision in one situation shall not be considered a
waiver of the performance of the provision in the future or a waiver of the
provision in its entirety.
6.5 Continuation
----------------
If any provision of this Agreement is found void and unenforceable, such
provision will be replaced to the extent possible with a provision that comes
closest to the meaning of the original provision and which is enforceable.
The terms and conditions set forth in this Agreement shall apply
notwithstanding any failure of essential purpose of this Agreement or any
limited remedy to the maximum extent possible under law.
::
Name: _________________________________________________
Email: ________________________________________________
Address: ______________________________________________
Address (cont): _______________________________________
Country: ______________________________________________
Phone number: _________________________________________
Fax number: ___________________________________________
_______________________________________________________
Signature
Mayan EDMS Entity CAA Version 1.0 April 8, 2018

243
docs/chapters/development/caa_individual.txt Normal file
View File

@@ -0,0 +1,243 @@
======================================================
Mayan EDMS Individual Contributor Assignment Agreement
======================================================
Thank you for your interest in contributing to Mayan EDMS ("We" or "Us").
This contributor agreement ("Agreement") documents the rights granted by
contributors to Us. To make this document effective, please print it, sign it
(by copyright holder or authorized party) and send it to Us by email to
caa@mayan-edms.com. This is a legally binding document, so please read it
carefully before agreeing to it. The Agreement may cover more than one
software project managed by Us.
1. Definitions
==============
"You" means the individual who Submits a Contribution to Us.
"Contribution" means any work of authorship that is Submitted by You to Us
in which You own or assert ownership of the Copyright. We cannot accept
contributions for which you do not own the Copyright or for which you don't
have the necessary legal power to transfer.
"Copyright" means all rights protecting works of authorship owned or
controlled by You, including copyright, moral and neighboring rights,
as appropriate, for the full term of their existence including any extensions
by You.
"Material" means the work of authorship which is made available by Us to third
parties. When this Agreement covers more than one software project, the Material
means the work of authorship to which the Contribution was Submitted. After
You Submit the Contribution, it may be included in the Material.
"Submit" means any form of electronic, verbal, or written communication
sent to Us or our representatives, including but not limited to
electronic mailing lists, source code control systems, and issue tracking systems
that are managed by, or on behalf of, Us for the purpose of discussing and
improving the Material, but excluding communication that is conspicuously marked
or otherwise designated in writing by You as "Not a Contribution."
"Submission Date" means the date on which You Submit a Contribution to Us.
"Effective Date" means the date You execute this Agreement or the date You first
Submit a Contribution to Us, whichever is earlier.
2. Grant of Rights
==================
2.1 Copyright Assignment
------------------------
a. At the time the Contribution is Submitted, You assign to Us all right,
title, and interest worldwide in all Copyright covering the Contribution;
provided that this transfer is conditioned upon compliance with Section 2.3.
b. To the extent that any of the rights in Section 2.1(a) cannot be assigned
by You to Us, You grant to Us a perpetual, worldwide, exclusive, royalty-free,
transferable, irrevocable license under such non-assigned rights, with rights
to sublicense through multiple tiers of sublicensees, to practice such
non-assigned rights, including, but not limited to, the right to reproduce,
modify, display, perform and distribute the Contribution; provided that
this license is conditioned upon compliance with Section 2.3.
c. To the extent that any of the rights in Section 2.1(a) can neither be
assigned nor licensed by You to Us, You irrevocably waive and agree never to
assert such rights against Us, any of our successors in interest, or any of
our licensees, either direct or indirect; provided that this agreement not
to assert is conditioned upon compliance with Section 2.3.
d. Upon such transfer of rights to Us, the Contribution will be licenses under
the terms of the Material.
2.2 Patent License
------------------
For patent claims including, without limitation, method, process, and apparatus
claims which You own, control or have the right to grant, now or in the future,
You grant to Us a perpetual, worldwide, non-exclusive, transferable, royalty-free,
irrevocable patent license, with the right to sublicense these rights to multiple
tiers of sublicensees, to make, have made, use, sell, offer for sale, import and
otherwise transfer the Contribution and the Contribution in combination with
the Material (and portions of such combination). This license is granted only
to the extent that the exercise of the licensed rights infringes such patent claims;
and provided that this license is conditioned upon compliance with Section 2.3.
2.3 Outbound License
--------------------
As a condition on the grant of rights in Sections 2.1 and 2.2, We agree to
license the Contribution only under the terms of the license or licenses which
We are using on the Submission Date for the Material (including any rights to
adopt any future version of a license if permitted).
2.4 Moral Rights
----------------
If moral rights apply to the Contribution, to the maximum extent permitted by law,
You waive and agree not to assert such moral rights against Us or our successors
in interest, or any of our licensees, either direct or indirect.
2.5 Our Rights
--------------
You acknowledge that We are not obligated to use Your Contribution as part of
the Material and may decide to include any Contribution We consider appropriate.
2.6 Reservation of Rights
-------------------------
Any rights not expressly assigned or licensed under this section are expressly
reserved by You.
3. Agreement
============
You confirm that:
a. You have the legal authority to enter into this Agreement.
b. You own the Copyright and patent claims covering the Contribution which are
required to grant the rights under Section 2.
c. The grant of rights under Section 2 does not violate any grant of rights
which You have made to third parties, including Your employer. If You are an
employee, You have had Your employer approve this Agreement or sign the Entity
version of this document. If You are less than eighteen years old, please have
Your parents or guardian sign the Agreement.
4. Disclaimer
=============
EXCEPT FOR THE EXPRESS WARRANTIES IN SECTION 3, THE CONTRIBUTION IS PROVIDED
"AS IS". MORE PARTICULARLY, ALL EXPRESS OR IMPLIED WARRANTIES INCLUDING, WITHOUT
LIMITATION, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY DISCLAIMED BY YOU TO US AND BY US
TO YOU. TO THE EXTENT THAT ANY SUCH WARRANTIES CANNOT BE DISCLAIMED, SUCH
WARRANTY IS LIMITED IN DURATION TO THE MINIMUM PERIOD PERMITTED BY LAW.
5. Consequential Damage Waiver
==============================
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL YOU OR US
BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF ANTICIPATED SAVINGS, LOSS OF DATA,
INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL AND EXEMPLARY DAMAGES ARISING OUT
OF THIS AGREEMENT REGARDLESS OF THE LEGAL OR EQUITABLE THEORY (CONTRACT, TORT
OR OTHERWISE) UPON WHICH THE CLAIM IS BASED.
6. Miscellaneous
================
6.1 Jurisdiction
----------------
This Agreement will be governed by and construed in accordance with the laws of
Puerto Rico excluding its conflicts of law provisions. Under certain circumstances,
the governing law in this section might be superseded by the United Nations
Convention on Contracts for the International Sale of Goods ("UN Convention")
and the parties intend to avoid the application of the UN Convention to this
Agreement and, thus, exclude the application of the UN Convention in its
entirety to this Agreement.
6.2 Acceptance
--------------
This Agreement sets out the entire agreement between You and Us for Your
Contributions to Us and overrides all other agreements or understandings.
6.3 Third parties
-----------------
If You or We assign the rights or obligations received through this Agreement
to a third party, as a condition of the assignment, that third party must
agree in writing to abide by all the rights and obligations in the Agreement.
6.4 Unmet responsibilities
--------------------------
The failure of either party to require performance by the other party of any
provision of this Agreement in one situation shall not affect the right of a
party to require such performance at any time in the future. A waiver of
performance under a provision in one situation shall not be considered a
waiver of the performance of the provision in the future or a waiver of the
provision in its entirety.
6.5 Continuation
----------------
If any provision of this Agreement is found void and unenforceable,
such provision will be replaced to the extent possible with a provision that
comes closest to the meaning of the original provision and which is enforceable.
The terms and conditions set forth in this Agreement shall apply notwithstanding
any failure of essential purpose of this Agreement or any limited remedy to
the maximum extent possible under law.
::
Name: _________________________________________________
Email: ________________________________________________
Address: ______________________________________________
Address (cont): _______________________________________
Country: ______________________________________________
Phone number: _________________________________________
Fax number: ___________________________________________
_______________________________________________________
Signature
Mayan EDMS Individual CAA Version 1.0 April 8, 2018

242
docs/chapters/development/code_structure.txt Normal file
View File

@@ -0,0 +1,242 @@
==============
Code structure
==============
Follow PEP8
-----------
Whenever possible, but don't obsess over things like line length:
.. code-block:: bash
$ flake8 --ignore=E501,E128,E122 |less
To perform automatic PEP8 checks, install flake8's git hook using:
.. code-block:: bash
$ flake8 --install-hook git
Imports
-------
Import order should be:
- Standard Python modules
- Installed Python modules
- Core Django modules
- Installed Django modules
- Mayan EDMS modules
- Local imports
Example:
.. code-block:: bash
from __future__ import absolute_import
# Standard Python library
import base64
# 3rd party installed Python libraries
import requests
# Django core modules
from django.db.models import Q
from django.template.defaultfilters import slugify
from django.utils.translation import ugettext
from django.utils.translation import ugettext_lazy as _
# 3rd party installed Django libraries
from rest_framework import APIView
# Mayan apps
from metadata.classes import MetadataClass
# Local app imports (relative)
from .conf.settings import (
AVAILABLE_INDEXING_FUNCTIONS,
MAX_SUFFIX_COUNT, SLUGIFY_PATHS
)
from .exceptions import MaxSuffixCountReached
from .filesystem import (
fs_create_index_directory, fs_create_document_link,
fs_delete_document_link, fs_delete_index_directory,
assemble_suffixed_filename
)
from .models import Index, IndexInstanceNode, DocumentRenameCount
All local app module imports are in relative form. Local app module name is to
be referenced as little as possible, unless required by a specific feature,
trick, restriction (e.g., Runtime modification of the module's attributes).
Incorrect:
.. code-block:: bash
# documents app views.py model
from documents.models import Document
Correct:
.. code-block:: bash
# documents app views.py model
from .models import Document
Dependencies
------------
Mayan EDMS apps follow a hierarchical model of dependency. Apps import from
their parents or siblings, never from their children. Think plugins. A parent
app must never assume anything about a possible existing child app. The
documents app and the Document model are the basic entities; they must never
import anything else. The common and main apps are the base apps.
Variables
---------
Naming of variables should follow a Major to Minor convention, usually
including the purpose of the variable as the first piece of the name, using
underscores as spaces. camelCase is not used in Mayan EDMS.
Examples:
Links:
.. code-block:: bash
link_document_page_transformation_list = ...
link_document_page_transformation_create = ...
link_document_page_transformation_edit = ...
link_document_page_transformation_delete = ...
Constants:
.. code-block:: bash
PERMISSION_SMART_LINK_VIEW = ...
PERMISSION_SMART_LINK_CREATE = ...
PERMISSION_SMART_LINK_DELETE = ...
PERMISSION_SMART_LINK_EDIT = ...
Classes:
.. code-block:: bash
class Document(models.Model):
class DocumentPage(models.Model):
class DocumentPageTransformation(models.Model):
class DocumentType(models.Model):
class DocumentTypeFilename(models.Model):
Strings
-------
Quotation character used in Mayan EDMS for strings is the single quote.
Double quote is used for multiple line comments or HTML markup.
Migrations
----------
Migrations should do only one thing (example: either create a table, move data
to a new table or remove an old table) to aid retrying on failure.
General
-------
Code should appear in their modules in alphabetic order or in their order of
importance if it makes more sense for the specific application. This makes
visual scanning easier on modules with a large number of imports, views or
classes. Class methods that return a value should be pretended with a
``get_`` to differentiate from an object’s properties. When a variable refers
to a file it should be named as follows:
- filename: The file’s name and extension only.
- filepath: The entire path to the file including the filename.
- path: A path to a directory.
Flash messages should end with a period as applicable for the language.
Only exception is when the tail of the message contains an exceptions message
as passed directly from the exception object.
Steps to deploy a development version
=====================================
.. code-block:: bash
$ git clone https://gitlab.com/mayan-edms/mayan-edms.git
$ cd mayan-edms
$ git checkout <Corresponding branch>
$ virtualenv venv
$ source venv/bin/activate
$ pip install -r requirements.txt
$ ./manage.py initialsetup
$ ./manage.py runserver
Debugging
=========
Mayan EDMS makes extensive use of Django's new
:django-docs:`logging capabilities <topics/logging>`.
By default debug logging for all apps is turned on. If you wish to customize
how logging is managed turn off automatic logging by setting
`COMMON_AUTO_LOGGING` to ``False`` and add the following lines to your
``settings/local.py`` file::
LOGGING = {
'version': 1,
'disable_existing_loggers': True,
'formatters': {
'verbose': {
'format': '%(levelname)s %(asctime)s %(name)s %(process)d %(thread)d %(message)s'
},
'intermediate': {
'format': '%(name)s <%(process)d> [%(levelname)s] "%(funcName)s() %(message)s"'
},
'simple': {
'format': '%(levelname)s %(message)s'
},
},
'handlers': {
'console':{
'level':'DEBUG',
'class':'logging.StreamHandler',
'formatter': 'intermediate'
}
},
'loggers': {
'documents': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},
'common': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},
}
}
Likewise, to see the debug output of the ``tags`` app, just add the following inside the ``loggers`` block::
'tags': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},

18
docs/chapters/development/contributing.txt Normal file
View File

@@ -0,0 +1,18 @@
============
Contributing
============
Mayan EDMS is under active development, and contributions are welcome.
If you have a feature request, suggestion or bug report, please open a new
issue on the `GitLab issue tracker`_. To submit patches, please send a merge
request on GitLab_.
.. _GitLab: https://gitlab.com/mayan-edms/mayan-edms/
.. _`GitLab issue tracker`: https://gitlab.com/mayan-edms/mayan-edms/issues
Contributing changes
====================
Follow the latest contributing guidelines outlined here:
https://gitlab.com/mayan-edms/mayan-edms/blob/master/CONTRIBUTING.md

24
docs/chapters/development/documentation.txt Normal file
View File

@@ -0,0 +1,24 @@
=============
Documentation
=============
The documentation is written in `reStructured Text`_ format, processed with
Sphinx_, and resides in the ``docs`` directory. In order to build it, you will
first need to install the documentation editing dependencies with::
$ pip install -r requirements/documentation.txt
Then, to build an HTML version of the documentation, run the following command
from the **docs** directory::
$ make docs-serve
The generated documentation can be viewed by browsing to http://127.0.0.1:8000
or by browsing to the ``docs/_build/html`` directory.
You can also generate the documentation in formats other than HTML. Consult the
Sphinx_ documentation for more details.
.. _`reStructured Text`: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx.pocoo.org

29
docs/chapters/development/index.txt Normal file
View File

@@ -0,0 +1,29 @@
==============
For developers
==============
- :doc:`philosophies`
- :doc:`code_structure`
- :doc:`documentation`
- :doc:`source_control`
- :doc:`contributing`
- :doc:`releases`
- :doc:`translations`
- :doc:`../../mercs/index`
- :doc:`caa_entity`
- :doc:`caa_individual`
.. toctree::
:hidden:
philosophies
code_structure
documentation
source_control
contributing
releases
translations
../../mercs/index
caa_entity
caa_individual

29
docs/chapters/development/philosophies.txt Normal file
View File

@@ -0,0 +1,29 @@
====================
Project philosophies
====================
How to think about Mayan EDMS when doing changes or adding new features;
why things are the way they are in Mayan EDMS:
- Functionality must be as market/sector independent as possible, code for the
95% of use cases.
- Each user must be able to configure and customize it to their needs after
install.
- Abstract as much as possible, each app must be an expert in just one thing,
for other things they should use the API/classes/functions of other apps.
- Assume as little as possible about anything outside the project
(hardware, OS, storage).
- Provide Python based abstraction so that a default install runs with a single
step.
- No hard dependencies on binaries unless there is no other choice.
- Provide “drivers” or switchable backends to allow users to fine tune the
installation.
- Call to binaries only when there is no other choice or the Python choices are
not viable/mature/efficient.
- Each app is as independent and self contained as possible. Exceptions, the
basic requirements: navigation, permissions, common, main.
- If an app is meant to be used by more than one other app, it should be as
generic as possible in regard to the project and another app will bridge the functionality.
- Example: since indexing (document_indexing) only applies to documents, the
app is specialized and depends on the documents app.

162
docs/chapters/development/releases.txt Normal file
View File

@@ -0,0 +1,162 @@
===================
Installable package
===================
Source file package
-------------------
This is the sequence of step used to produce an installable package:
1. Generate the packaged version (will produce dist/mayan-edms-x.y.z.tar.gz)::
$ make sdist
2. Do a test install::
$ cd /tmp
$ virtualenv venv
$ source venv/bin/activate
$ pip install <path of the Git repository>/dist/mayan-edms-x.y.z.tar.gz
$ mayan-edms.py initialsetup
$ mayan-edms.py runserver
Wheel package
-------------
1. Install the development requirements::
$ pip install -r requirements/development.txt
2. Create wheel package using the makefile::
$ make wheel
3. Do a test install::
$ cd /tmp
$ virtualenv venv
$ source venv/bin/activate
$ pip install <path of the Git repository>/dist/mayan_edms-x.y.z-py2-none-any.whl
$ mayan-edms.py initialsetup
$ mayan-edms.py runserver
Version numbering
=================
Mayan EDMS uses the Semantic Versioning (http://semver.org/) method to choose
version numbers along with Python's PEP-0440 (https://www.python.org/dev/peps/pep-0440/)
to format them.
X.YaN # Alpha release
X.YbN # Beta release
X.YrcN # Release Candidate
X.Y # Final release
Release checklist
=================
#. Check for missing migrations::
make check-missing-migrations
#. Synchronize translations::
make translations-pull
#. Compile translations::
make translations-compile
#. Update changelog.
#. Write release notes.
#. Scan the code with flake8 for simple style warnings.
#. Check README.rst format with::
python setup.py check -r -s
or with::
make check-readme
#. Bump version in ``mayan/__init__.py`` and ``docker/rootfs/version``::
make increase-version PART=<major, minor or micro>
#. Update requirements version in ``setup.py`` using:
::
make generate-setup
#. Commit as version bump.
#. Build source package and test:
::
make test-sdist-via-docker-ubuntu
#. Build wheel package and test:
::
make test-wheel-via-docker-ubuntu
#. Tag version:
::
git tag -a vX.Y.Z -m "Version X.Y.Z"
#. Generate set ``setup.py`` again to update the build number::
make generate-setup
#. Commit the new ``setup.py`` file.
#. Release the version using one of the two following methods: GitLab CI or
manual
Release using GitLab CI
-----------------------
#. Push the current brach:
::
git push
#. Push the new tags:
::
git push --tags
#. Delete the corresponding ``releases/`` branch:
::
git push origin :releases/<branch>
#. Push the current branch to the corresponding origin ``releases/`` branch:
::
git push origin <local branch>:releases/<branch>
Manual release
--------------
#. Build and upload a test release:
::
make release-test-via-docker-ubuntu
#. Build and upload a final release:
::
make release-via-docker-ubuntu
Other steps
-----------
#. Update the contrib/scripts/install/docker.sh values
#. Upload contrib/scripts/install/docker.sh to https://get.mayan-edms.com

102
docs/chapters/development/source_control.txt Normal file
View File

@@ -0,0 +1,102 @@
==============
Source Control
==============
Mayan EDMS source is controlled with Git_.
The project is publicly accessible, hosted and can be cloned from **GitLab** using::
$ git clone https://gitlab.com/mayan-edms/mayan-edms.git
Git branch structure
--------------------
Mayan EDMS follows a simplified model layout based on Vincent Driessen's
`Successful Git Branching Model`_ blog post.
``/versions/micro``
Working branch for the next bugfix release. Micro increment (third digit).
Only bug fixes, minor features, back-ported urgent features. This
branch is stable and safe for production.
``/versions/minor``
Working branch for the next minor release (second digit). New features,
occasional breakage. Not for production but should run in test
environment most of the time. This is the branch you will want to
try out if you want to check out new features.
``/versions/major``
Working branch for the next major release (first digit). New features,
incompatible changes to the user facing interfaces. Broken most of the
time, not for production and should only be cloned by developers
with experience with Mayan's development.
``master``
Current production release (|version|). Points to the latest version of
the latest series. Production quality code.
``features/``
Working branches for unfinished and unmerged feature. Likely unstable,
don't use in production. Once the feature is complete, it is merged
into one of the versions branches and deleted.
Special branches:
``releases/all``
Pushing code to this branch will trigger the build and release
a new Docker image, Documentation and Python package.
``releases/docker``
Pushing code to this branch will trigger the build and release
of a new Docker image to Docker Hub.
``releases/documentation``
Pushing code to this branch will trigger the build and release
of new documentation.
``releases/python``
Pushing code to this branch will trigger the build and release
of a new Python package to PyPI.
``nightly``
Pushing code to this branch will trigger the build and release
of a new Docker image based on development code to the GitLab image
repository only. The image will not be published to Docker Hub.
Each release is tagged separately using annotated Git tags.
When submitting patches, please place your code in its own ``feature/`` branch
prior to opening a Merge Request on GitLab_.
.. _Git: http://git-scm.org
.. _`Successful Git Branching Model`: http://nvie.com/posts/a-successful-git-branching-model/
Commit messages
---------------
#. Use English as the language for the commit messages.
#. Provide a subject line composed of a tag and a short explanation::
Indexing: Add document base property reindex
#. Keep the subject line to 50 or less characters.
#. Capitalize the subject line.
#. Don't end the subject line with a period, leave like a phrase in English.
#. Use active voice in the. Say what the commit will do when applied not what
you did::
Add new properties to the model.
Vs.
::
Added new properties to the model.
#. Limit the body of the commit to 72 characters.
#. When a commit fixes or improves an issue add the issue number in the commit
message. Either in the subject or in the body.
#. Sign commit messages.
#. Use explicit language even for minor commits. Don't do::
Fix typo
Use::
Document: Fix typo in label description
.. _GitLab: https://gitlab.com/mayan-edms/mayan-edms/

17
docs/chapters/development/translations.txt Normal file
View File

@@ -0,0 +1,17 @@
============
Translations
============
Translations are handled online via the **Transifex** website:
https://www.transifex.com/projects/p/mayan-edms/. To create a translation team
for a new language or contribute to an already existing language translation,
create a **Transifex** account and contact the team coordinator of the
respective language in which you are interested.
Feel free to open translation issues inside **Transifex** itself if you have a
question about the usage or meaning of a source text string. If you open a
translation issue, it will be your responsibility to close it after you get an
answers that satisfies your question. Administrator will not close new issues
as they have no way to determine if your question has been properly answered.
However to avoid clutter, answered questions will be scanned periodically and
closed if no activity is observed from the original poster in a period of time.