22.9 (#60)

* Documentation improvements * Testing black linting * Testing black linting * reducing dependency on settings * reducing dependency on settings * reducing dependency on settings * Typo removal * configuring black linting * automatic blacking of the code * automatic blacking of the code * automatic blacking of the code * optimising imports * black * testing build action with v2 * reverted settings * Black shield added * Added accounting number to writers * Accounting number now appears in outgoing royalty statements, updated documentation * Updated releases.rst * Updated releases.rst and improved test coverage * Updated releases.rst and improved test coverage * Fixes related to writer.account_number * Fixes related to writer.account_number * Fixes related to writer.account_number * Fixes related to writer.account_number * Improved introduction * Improved introduction * Code complexity reduced to D * Code complexity in models.py reduced to C * Bumping versions of everything * replacing assert with proper exceptions * blacked * started work on DDEX ERN exports - DPID validation added * added added XML template and action, the work starts * removed API links to private artists, added artist to releases, etc. * fixed build script * blacked everything * Releases.txt extended with text about EBR. * CWR_CODE now defaults to "000", and default publisher IP to "P000001" * Lagunage code for docs set to "en" * updated README * Update README.rst * changed test CWR files to match the new formar * improving CC - no more Ds * documentation updates - QA * documentation updates - QA * work on EBR 4.2 * blacked * Procfile * EBR removed * fixed for merging
matijakolaric-com · Sep 28, 2022 · ae1fd48 · ae1fd48
1 parent cc57ef4
commit ae1fd48
Show file tree

Hide file tree

Showing 35 changed files with 899 additions and 283 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -6,9 +6,16 @@ on:
     - 'static/**'
   pull_request:
     branches:
-      - main
+      - master
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: psf/black@stable
+        with:
+          options: "--check --verbose --line-length 79 --exclude music_publisher/migrations"
   build:
     runs-on: ubuntu-latest
     services:
@@ -25,15 +32,15 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v1
+      uses: actions/checkout@v2
 
     - name: Setup Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v2
       with:
         python-version: ${{ matrix.python }}
 
     - name: Setup cache for pip
-      uses: actions/cache@v1
+      uses: actions/cache@v2
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
@@ -57,4 +64,4 @@ jobs:
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       run: |
-        coveralls --service=github
+        coveralls --service=github
diff --git a/README.rst b/README.rst
@@ -1,24 +1,39 @@
 Django-Music-Publisher - Free music publishing software
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-.. image:: https://github.com/matijakolaric-com/django-music-publisher/workflows/build/badge.svg?branch=master
+.. image:: https://github.com/matijakolaric-com/django-music-publisher/workflows/build/badge.svg?branch=master&logo=pypi&logoColor=white
     :target: https://github.com/matijakolaric-com/django-music-publisher/actions/workflows/build.yml
     :alt: Build Status
-.. image:: https://img.shields.io/readthedocs/django-music-publisher?logo=read-the-docs   
+.. image:: https://img.shields.io/github/issues/matijakolaric-com/django-music-publisher/bug?logo=github&logoColor=white
+    :target: https://github.com/matijakolaric-com/django-music-publisher/issues
+    :alt: GitHub issues
+.. image:: https://img.shields.io/readthedocs/django-music-publisher?logo=read-the-docs&logoColor=white   
     :target: https://django-music-publisher.readthedocs.io/en/latest/
     :alt: Documentation Status
-.. image:: https://img.shields.io/coveralls/github/matijakolaric-com/django-music-publisher/master?logo=coveralls&branch=master
+.. image:: https://img.shields.io/coveralls/github/matijakolaric-com/django-music-publisher/master?logo=coveralls&branch=master&logoColor=white
     :target: https://coveralls.io/github/matijakolaric-com/django-music-publisher?branch=master
     :alt: Coverage Status
-.. image:: https://img.shields.io/github/license/matijakolaric-com/django-music-publisher.svg?logo=github
-    :target: https://github.com/matijakolaric-com/django-music-publisher/blob/master/LICENSE
-    :alt: License
-.. image:: https://img.shields.io/pypi/v/django-music-publisher.svg?logo=pypi
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+    :alt: Code Style
+.. image:: https://img.shields.io/pypi/v/django-music-publisher.svg?logo=pypi&logoColor=white
     :target: https://pypi.org/project/django-music-publisher/
     :alt: PYPI
-.. image:: https://img.shields.io/github/issues/matijakolaric-com/django-music-publisher/bug?logo=github
-    :target: https://github.com/matijakolaric-com/django-music-publisher/issues
-    :alt: GitHub issues
+.. image:: https://img.shields.io/pypi/wheel/django-music-publisher?logo=pypi&logoColor=white
+    :target: https://pypi.org/project/django-music-publisher/
+    :alt: PyPI - Wheel
+.. image:: https://img.shields.io/pypi/status/django-music-publisher?logo=pypi&logoColor=white
+    :target: https://pypi.org/project/django-music-publisher/
+    :alt: PyPI - Status
+.. image:: https://img.shields.io/pypi/djversions/django-music-publisher?logo=pypi&logoColor=white
+    :target: https://pypi.org/project/django-music-publisher/
+    :alt: PyPI - Django Version
+.. image:: https://img.shields.io/pypi/pyversions/django-music-publisher?logo=pypi&logoColor=white
+    :target: https://pypi.org/project/django-music-publisher/
+    :alt: PyPI - Python Version
+.. image:: https://img.shields.io/github/license/matijakolaric-com/django-music-publisher.svg?logo=github&logoColor=white
+    :target: https://github.com/matijakolaric-com/django-music-publisher/blob/master/LICENSE
+    :alt: License
 
 Django-Music-Publisher (DMP) is open source software for **managing music metadata**, **registration/licencing of musical works**, **royalty management** and **music data distribution**.
 

diff --git a/dmp_project/settings.py b/dmp_project/settings.py
@@ -125,7 +125,7 @@
 SECURE_SSL_REDIRECT = not DEBUG
 
 # The name of the publisher. Use no comma in the name!
-PUBLISHER_NAME = os.getenv("PUBLISHER", "FREE MUSIC CATALOGUE SOFTWARE")
+PUBLISHER_NAME = os.getenv("PUBLISHER", "DMP - FREE MUSIC CATALOGUE SOFTWARE")
 
 # CWR Delivery code, issued by collecting societies
 PUBLISHER_CODE = os.getenv("PUBLISHER_CODE", "")

diff --git a/docs/conf.py b/docs/conf.py
@@ -23,14 +23,14 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "Django-Music-Publisher - Free Music Publishing Software -"
-copyright = "2018-2021, Matija Kolarić"
+project = "DMP - Free Music Publishing Software -"
+copyright = "2018-2022, Matija Kolarić"
 author = "Matija Kolarić"
 
 # The short X.Y version
-version = "22.1 Exofile"
+version = "22.9 Rubicon"
 # The full version, including alpha/beta/rc tags
-release = "22.1"
+release = "22.9"
 
 rst_epilog = """
 .. |version| replace:: {}
@@ -77,7 +77,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -156,8 +156,8 @@
 latex_documents = [
     (
         master_doc,
-        "DjangoMusicPublisher.tex",
-        "Django-Music-Publisher Documentation",
+        "DMP.tex",
+        "DMP Documentation",
         "Matija Kolarić",
         "manual",
     )
@@ -171,8 +171,8 @@
 man_pages = [
     (
         master_doc,
-        "djangomusicpublisher",
-        "Django-Music-Publisher Documentation",
+        "dmp",
+        "DMP Documentation",
         [author],
         1,
     )
@@ -187,10 +187,10 @@
 texinfo_documents = [
     (
         master_doc,
-        "DjangoMusicPublisher",
-        "Django-Music-Publisher Documentation",
+        "DMP",
+        "DMP Documentation",
         author,
-        "DjangoMusicPublisher",
+        "DMP",
         "Open source solution for original music publishers.",
         "Miscellaneous",
     )

diff --git a/docs/images/add_writer.png b/docs/images/add_writer.png
diff --git a/docs/images/add_writer_popup.png b/docs/images/add_writer_popup.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -17,6 +17,7 @@ DMP
    introduction
    features
    support
+   qa
    videos
    installation
    releases

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -83,13 +83,18 @@ There are several required `settings`_.
 Settings
 ===================================
 
+Secret key
+-----------------------------------
+
+Django requires ``SECRET_KEY`` to be set.
+
 Publisher-related settings
 -----------------------------------
 
 * ``PUBLISHER_NAME`` - Name of the publisher using Django-Music-Publisher, required
-* ``PUBLISHER_CODE`` - Publisher's CWR Delivery code, without it CWR generation will not work.
 * ``PUBLISHER_IPI_BASE`` - Publisher's IPI *Base* Number, rarely used
 * ``PUBLISHER_IPI_NAME`` - Publisher's IPI *Name* Number, required
+* ``PUBLISHER_CODE`` - Publisher's CWR Delivery code, defaults to ``000``, which is not accepted by CMOs, but may be accepted by (sub-)publishers.
 * ``PUBLISHER_SOCIETY_PR`` - Publisher's performance collecting society (PRO) numeric code, required
 * ``PUBLISHER_SOCIETY_MR`` - Publisher's mechanical collecting society (MRO) numeric code
 * ``PUBLISHER_SOCIETY_SR`` - Publisher's synchronization collecting society numeric code, rarely used

diff --git a/docs/introduction.rst b/docs/introduction.rst
@@ -112,9 +112,9 @@ Output is a similar CSV file with additional rows and columns.
         Publisher Excel->>Writer: Outgoing Royalty Statement
         Publisher Excel->>Accounting: Accounting data
 
-This file can be then imported into excel and turned into individual
+This file can be then imported into Excel and turned into individual
 outgoing statements and accounting data using pivot tables. This process
-can be automated using simple scripts.
+can be automated using Excel templates and simple scripts.
 
 Data Distribution
 ++++++++++++++++++++++++++++++++++

diff --git a/docs/manual_cwrexport.rst b/docs/manual_cwrexport.rst
@@ -23,7 +23,8 @@ Add View
    Add CWR export view
 
 .. note::
-    CWR exports can be created only if *CWR delivery code* is entered as ``PUBLISHER_CODE`` in :ref:`settings`.
+    If *CWR delivery code* is not entered as ``PUBLISHER_CODE`` in :ref:`settings`, ``000`` will be
+    used. Such CWR files will not be accepted by most CMOs, but may be accepted by (sub-)publishers.
 
 .. warning::
     Do NOT use an arbitratry CWR delivery code for creating CWR exports.

diff --git a/docs/manual_royaltycalculations.rst b/docs/manual_royaltycalculations.rst
@@ -1,6 +1,12 @@
 Royalty Calculations
 ==============================
 
+If you are interested in the complete Royalty Management process,
+please read the articles about 
+`Royalty Management with DMP <https://matijakolaric.com/articles/royalty-management/>`_,
+or watch the relevant videos from :doc:`videos`.
+This document describes only a single step in this process.
+
 .. figure:: /images/royaltystatement.png
    :width: 100%
 
@@ -61,6 +67,7 @@ Both algorithms add these columns:
 
 * ``Controlled by publisher (%)``
 * ``Interested party``
+* ``IP Account Number``
 * ``Role``
 * ``Share in amount received (%)``
 * ``Net amount``

diff --git a/docs/manual_writer.rst b/docs/manual_writer.rst
@@ -11,6 +11,13 @@ Add/Change View
 
 ``Add`` and ``change`` views for writers have several fieldsets.
 
+Writer ID and Account Number
+++++++++++++++++++++++++++++
+
+At the top, before the first fieldset are two fields, ``Writer ID``, assigned by the system
+and not editable, and ``Account #``, used for linking data from DMP with your accounting, when
+processing royalty statements.
+
 Name
 ++++
 

diff --git a/docs/qa.rst b/docs/qa.rst
@@ -0,0 +1,108 @@
+Quality Assurance
+#####################
+
+This project is now over four years old and, as any continuously
+developed project, has legacy issues. If anyone tells you that their
+project has no legacy issues, they are either ignorant or lying. 
+Probably both.
+
+Here is how issues are reduced, caught and fixed in this project.
+
+Test coverage, Continuous Integration, Continuous Deployment
+=================================================================
+
+Test Coverage
+++++++++++++++++++++++
+
+For years, test coverage was around 99% (mostly functional tests), and 
+the goal is to keep it over 99.5% (rounded to 100%) for major releases.
+
+Continuous Integration
+++++++++++++++++++++++++++++++
+
+These tests are run on every push to the code repository, 
+(together with code style validation).
+
+Continuous Deployment
+++++++++++++++++++++++++++++++
+
+If tests pass, the code is automatically deployed. 
+
+Manual Testing
+++++++++++++++++++++++++++++++++
+
+CD instance is used for creating screenshots for documentation 
+and videos. Before each major release, all functionality is
+manually tested.
+
+Of course, there is a small chance that some edge case is not covered,
+and that someone will hit a bug in production, but it is reduced to the
+minimum.
+
+Code Style, Complexity and Maintainability
+========================================================
+
+Some of these issues can be detected and/or measured, sometimes even 
+fixed, with standard tools. Code style, complexity and maintainability 
+are good examples.
+
+Code Style
++++++++++++++++++
+Code style in this project is current Black, with line length of 79 
+characters. This is validated on every push.
+
+Code Complexity
+++++++++++++++++++
+
+Recently, code complexity has been improved. No code block has nor should 
+have complexity over ``C (20)``. Average should remain around ``A (3.0)``.
+
+Code Maintainability
++++++++++++++++++++++++++
+
+Code maintainability is to be improved, currently 2 files have dead low 
+index, due to their size. The goal is to have ``A`` across all files by
+the 23.4 release.
+
+Creativity of the one obvious way to do it
+=====================================================================
+
+All of these measures are about reducing the possibility of an issue
+arising, catching it when it does, and fixing it quickly without
+breaking something else. But, it has nothing to do with actual 
+development of new features. 
+
+Breaking the presumptions
+++++++++++++++++++++++++++++++++++++++++++++++++
+
+Until 2018, CWR was seen as something that only large
+publishers can use, due to it's complexity and expensive tools.
+Then DMP came out and shattered this, making CWR free and available
+to small publishers. In 2022, the mainstream belief in music
+publishing is that CWR is for everyone.
+
+Until 2020, most of the industry has believed that royalty management
+for music publishers is ... well, you know, only available to large 
+publishers, due to complexity and price.
+
+Until 2022 ... data exchange between publishers and labels ... 
+complex and expensive.
+
+QA without standards
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The question is how to assure quality if there are no standards and no 
+expectations that actually apply to your project? 
+(Except that it is impossible. Again.)
+
+Well, DMP fulfills all those that do apply (like CWR or DDEX EBR specs),
+validate everything can be validated (IPI, ISWC, DPID), except when
+breaking the rules is advantageous. (There is a reason why nearly everyone 
+believed something was impossible, until someone broke some rule.) 
+
+But, most of the rules are great, choosing which ones to break
+is a long process, in the three examples above, this choice took 
+many years.
+
+And, if you break a rule, you must make a new one and document it really
+well.
diff --git a/docs/releases.rst b/docs/releases.rst
@@ -146,15 +146,35 @@ Writers, artists, labels and releases received ``image`` and
 ``description`` fields, to be used in front-end representations.
 Recordings received an ``audio_file`` field.
 
-Read-only REST API endpoints are available for releases and recording artists,
-enabling integration with websites.
+Read-only REST API endpoints are available for releases and recording 
+artists, enabling integration with websites.
 
 Playlists can now be created, either by manually adding recordings,
 or by using batch actions in various list views, and shared
 using secret URLs.
 
 Full metadata backup can be download using REST API endpoint.
 
+22.9 Rubicon
+-------------------------------
+
+``Account #`` field was added to the ``Writer`` model. This field can
+be used for linking data from outgoing royalty statements with 
+accounting.
+
+Introduction chapter of this documentation was extended with graphs, 
+and split into two separate documents. Several external articles were 
+linked to improve clarity.
+
+Most improvements in this release are under the bonnet. The 
+source code has been reviewed and partly cleaned up, with average 
+complexity reduced to ``A (3.0)`` and no block more complex than 
+``C``. Code style is now validated with 
+`Black <https://black.readthedocs.io/en/stable/>`_.
+
+However, the most important new feature is the generation of
+DDEX ERN documents for commercial releases. Adding features for 
+labels will continue in next releases.
 
 Future open-source features
 ===========================