Move basic concepts into a separate file

barseghyanartur · Nov 17, 2019 · aa27091 · aa27091
1 parent 7b2749c
commit aa27091
Show file tree

Hide file tree

Showing 3 changed files with 173 additions and 154 deletions.
diff --git a/README.rst b/README.rst
@@ -27,136 +27,76 @@ Prerequisites
 =============
 - Python 3.6, 3.7, 3.8 and PyPy
 
-Use cases and basic concepts
-============================
-If the following applies to you, ``matyan`` could help:
-
-- Project releases (tags) are numbered according to the
-  `semantic versioning <https://semver.org/>`_ or
-  `sequence based identifiers <http://en.wikipedia.org/wiki/Software_versioning#Sequence-based_identifiers>`_.
-- Project follows the DTAP.
-- Testing, acceptance and production branches (hereafter referred as TAP
-  branches) are protected.
-- Direct commits to TAP branches are forbidden.
-- All commits to TAP branches are made by pull requests.
-- JIRA (or a similar tool) is used for handing project tickets.
-- Pull requests are merged using GitHub or BitBucket web interface.
-
-Sample use-case
----------------
-The use-case
-~~~~~~~~~~~~
-- JIRA is used for issues.
-- All commits are prefixed with ID of the JIRA issue: for example, `MSFT-1234`
-  or `NVDA-1234` (where first four letters identify the client commit was done
-  for, it's pattern).
-- There are 3 main (protected) branches: `dev`, `staging`, `master`.
-  Direct commits to any of the 3 are forbidden. Any feature/bugfix comes via
-  merge request.
-- All branches do have meaningful prefixes. Example,
-  `feature/MSFT-1234-Title-of-the-issue` or
-  `bugfix/MSFT-1236-prevent-duplicate-postal-codes`.
-- Release flow is `dev` -> `staging` -> `master`.
-
-Sample commits
-~~~~~~~~~~~~~~
-Consider the following commits into the dev branch:
-
-*branch: bugfix/MSFT-1240-LinkedIn-authentication-failing*
-
-- MSFT-1240 Fix package configuration.
-- MSFT-1240 Update authentication pipeline.
-
-*branch: deprecation/MSFT-1239-Deprecate-Python2*
-
-- MSFT-1239 Deprecate Python2.
-- MSFT-1238 Add initial MyPY setup.
-
-*branch: feature/MSFT-1238-Token-authentication*
-
-- MSFT-1238 Implement token authentication.
-- MSFT-1238 Update authentication docs.
-
-*branch: feature/MSFT-1237-Improve-document-sharing*
-
-- MSFT-1237 Improve document sharing. Add option to share via GDrive.
-
-*branch: bugfix/MSFT-1236-prevent-duplicate-postal-codes*
-
-- MSFT-1236 Normalise postal codes for German addresses.
-- MSFT-1236 Normalise postal codes for US addresses.
-- MSFT-1236 Make postal code field unique for the country.
-
-*branch: deprecation/MSFT-1235-deprecate-old-api*
-
-- MSFT-1235 Deprecate API v 2.0.
-- MSFT-1235 Update docs.
+Documentation
+=============
+Documentation is available on `Read the Docs
+<http://matyan.readthedocs.io/>`_.
 
-*branch: feature/MSFT-1234-car-type-suggester*
+Installation
+============
+Latest stable version on PyPI:
 
-- MSFT-1234 Initial car type suggester implementation.
-- MSFT-1234 Add insurance amount indication based on car weight.
+.. code-block:: sh
 
-Sample releases
-~~~~~~~~~~~~~~~
-All commits have been finally merged into master.
+    pip install matyan
 
-Releases have been made in the following way:
+Usage
+=====
+See `Basic concepts <https://matyan.readthedocs.io/en/latest/basic_concepts.html>`_
+section to get impression on possible commit methodology and assumptions taken.
 
-*0.1*
+**Generate changelog:**
 
-- Merged issues MSFT-1234, MSFT-1235 and MSFT-1236
+.. code-block:: sh
 
-*0.2*
+    generate-changelog
 
-- Merged issues MSFT-1237 and MSFT-1238
+**Generate changelog skipping orphaned commits:**
 
-*Yet unreleased features/branches*
+In some cases you only want to show what has been done with tickets and skip
+all non-ticket related commits.
 
-- MSFT-1239 and
+.. code-block:: sh
 
-Sample changelog output
------------------------
-The generated change log would look as follows:
+    generate-changelog --no-other
 
-.. code-block:: text
+**Generate changelog between two releases:**
 
-    ### 0.2
+In some cases you only want to show what has been done since last release.
+The following example would generate changelog since version 0.0.1 to
+version 0.0.3.
 
-    **Features**
+.. code-block:: sh
 
-    *MSFT-1238 Token-authentication*
+    generate-changelog 0.0.1..0.0.3
 
-    - Implement token authentication.
-    - Update authentication docs.
+**Generate changelog between two branches:**
 
-    *MSFT-1237 Improve document sharing*
+In some cases you only want to show what has been done since last release.
+The following example would generate changelog since version 0.0.1 to
+version 0.0.3.
 
-    - Improve document sharing. Add option to share via GDrive.
+.. code-block:: sh
 
-    ### 0.1
+    generate-changelog master..dev
 
-    **Bugfixes**
+**Generate changelog with releases info shown**
 
-    *MSFT-1236 Prevent duplicate postal codes*
+.. code-block:: sh
 
-    - Normalise postal codes for German addresses.
-    - Normalise postal codes for US addresses.
-    - Make postal code field unique for the country.
+    generate-changelog --show-releases
 
-    **Deprecations**
+**Generate changelog between releases with releases info shown**
 
-    *MSFT-1235 Deprecate old api*
+.. code-block:: sh
 
-    - Deprecate API v 2.0.
-    - Update docs.
+    generate-changelog 0.0.1..0.0.3 --show-releases
 
-    **Features**
+**Generate changelog between branches with releases info shown**
 
-    *MSFT-1234 Car type suggester*
+.. code-block:: sh
 
-    - Initial car type suggester implementation.
-    - Add insurance amount indication based on car weight.
+    generate-changelog master..dev --show-releases
 
 Configuration
 =============
@@ -206,58 +146,6 @@ Create initial config file
 
     matyan-create-config
 
-Documentation
-=============
-Documentation is available on `Read the Docs
-<http://matyan.readthedocs.io/>`_.
-
-Installation
-============
-Latest stable version on PyPI:
-
-.. code-block:: sh
-
-    pip install matyan
-
-Usage
-=====
-**Generate changelog:**
-
-.. code-block:: sh
-
-    generate-changelog
-
-**Generate changelog skipping orphaned commits:**
-
-In some cases you only want to show what has been done with tickets and skip
-all non-ticket related commits.
-
-.. code-block:: sh
-
-    generate-changelog --no-other
-
-**Generate changelog between two releases:**
-
-In some cases you only want to show what has been done since last release.
-The following example would generate changelog since version 0.0.1 to
-version 0.0.3.
-
-.. code-block:: sh
-
-    generate-changelog 0.0.1..0.0.3
-
-**Generate changelog with releases info shown**
-
-.. code-block:: sh
-
-    generate-changelog --show-releases
-
-**Generate changelog between releases with releases info shown**
-
-.. code-block:: sh
-
-    generate-changelog 0.0.1..0.0.3 --show-releases
-
 Testing
 =======
 Simply type:

diff --git a/docs/basic_concepts.rst b/docs/basic_concepts.rst
@@ -0,0 +1,130 @@
+Use cases and basic concepts
+============================
+If the following applies to you, ``matyan`` could help:
+
+- Project releases (tags) are numbered according to the
+  `semantic versioning <https://semver.org/>`_ or
+  `sequence based identifiers <http://en.wikipedia.org/wiki/Software_versioning#Sequence-based_identifiers>`_.
+- Project follows the DTAP.
+- Testing, acceptance and production branches (hereafter referred as TAP
+  branches) are protected.
+- Direct commits to TAP branches are forbidden.
+- All commits to TAP branches are made by pull requests.
+- JIRA (or a similar tool) is used for handing project tickets.
+- Pull requests are merged using GitHub or BitBucket web interface.
+
+Sample use-case
+---------------
+The use-case
+~~~~~~~~~~~~
+- JIRA is used for issues.
+- All commits are prefixed with ID of the JIRA issue: for example, `MSFT-1234`
+  or `NVDA-1234` (where first four letters identify the client commit was done
+  for, it's pattern).
+- There are 3 main (protected) branches: `dev`, `staging`, `master`.
+  Direct commits to any of the 3 are forbidden. Any feature/bugfix comes via
+  merge request.
+- All branches do have meaningful prefixes. Example,
+  `feature/MSFT-1234-Title-of-the-issue` or
+  `bugfix/MSFT-1236-prevent-duplicate-postal-codes`.
+- Release flow is `dev` -> `staging` -> `master`.
+
+Sample commits
+~~~~~~~~~~~~~~
+Consider the following commits into the dev branch:
+
+*branch: bugfix/MSFT-1240-LinkedIn-authentication-failing*
+
+- MSFT-1240 Fix package configuration.
+- MSFT-1240 Update authentication pipeline.
+
+*branch: deprecation/MSFT-1239-Deprecate-Python2*
+
+- MSFT-1239 Deprecate Python2.
+- MSFT-1238 Add initial MyPY setup.
+
+*branch: feature/MSFT-1238-Token-authentication*
+
+- MSFT-1238 Implement token authentication.
+- MSFT-1238 Update authentication docs.
+
+*branch: feature/MSFT-1237-Improve-document-sharing*
+
+- MSFT-1237 Improve document sharing. Add option to share via GDrive.
+
+*branch: bugfix/MSFT-1236-prevent-duplicate-postal-codes*
+
+- MSFT-1236 Normalise postal codes for German addresses.
+- MSFT-1236 Normalise postal codes for US addresses.
+- MSFT-1236 Make postal code field unique for the country.
+
+*branch: deprecation/MSFT-1235-deprecate-old-api*
+
+- MSFT-1235 Deprecate API v 2.0.
+- MSFT-1235 Update docs.
+
+*branch: feature/MSFT-1234-car-type-suggester*
+
+- MSFT-1234 Initial car type suggester implementation.
+- MSFT-1234 Add insurance amount indication based on car weight.
+
+Sample releases
+~~~~~~~~~~~~~~~
+All commits have been finally merged into master.
+
+Releases have been made in the following way:
+
+*0.1*
+
+- Merged issues MSFT-1234, MSFT-1235 and MSFT-1236
+
+*0.2*
+
+- Merged issues MSFT-1237 and MSFT-1238
+
+*Yet unreleased features/branches*
+
+- MSFT-1239 and
+
+Sample changelog output
+-----------------------
+The generated change log would look as follows:
+
+.. code-block:: text
+
+    ### 0.2
+
+    **Features**
+
+    *MSFT-1238 Token-authentication*
+
+    - Implement token authentication.
+    - Update authentication docs.
+
+    *MSFT-1237 Improve document sharing*
+
+    - Improve document sharing. Add option to share via GDrive.
+
+    ### 0.1
+
+    **Bugfixes**
+
+    *MSFT-1236 Prevent duplicate postal codes*
+
+    - Normalise postal codes for German addresses.
+    - Normalise postal codes for US addresses.
+    - Make postal code field unique for the country.
+
+    **Deprecations**
+
+    *MSFT-1235 Deprecate old api*
+
+    - Deprecate API v 2.0.
+    - Update docs.
+
+    **Features**
+
+    *MSFT-1234 Car type suggester*
+
+    - Initial car type suggester implementation.
+    - Add insurance amount indication based on car weight.
diff --git a/docs/documentation.rst.distrib b/docs/documentation.rst.distrib
@@ -8,6 +8,7 @@ Contents:
    :maxdepth: 20
 
    index
+   basic_concepts
    changelog
    matyan