Merge branch 'master' of https://github.com/silx-kit/silx-training

software_engineering/1_Architecture/index.rst

@@ -11,12 +11,13 @@
 =========================
 
 #. Have a clean structure
+#. Get ready for the future
 #. A word about licenses
 #. Coding convention
 
    #. PEP8
    #. PEP20
-
+#. Tools 
 #. Structure of a minimalistic project
 
 ----
@@ -28,12 +29,13 @@ Have a clean structure
 
   * libraries are reusable
 
-- Separate GUI from calculation:
+- Separate user interface from calculation:
 
   *  Otherwise maintenance becomes a nightmare
   *  allows to change the front-end
   *  allows to access to core function without the GUI
   *  simplify unit tests
+  *  ease collaboration
 
 - Separate I/O from calculation
 
@@ -49,10 +51,31 @@ Will also help you to :
 
 ----
 
-example
--------
+Python 2 end of life
+--------------------
+
+By 2020, the `support of Python2 will end <https://pythonclock.org/>`_.
+All your projects must be python3 based, supporting Python2 has become optional.
+
+
+Look at the `developer statistics <https://www.jetbrains.com/research/python-developers-survey-2018/#python-3-adoption>`_
+
+----
+
+Nice features of Python 3
+-------------------------
+
+Python3 prevents you from mixing tab and space indentation in your code.
+
+Python3 enforces you to decode early your data to avoid mixing *bytes* and *unicode*
+
+You can use the `six library <https://pypi.python.org/pypi/six>`_ to provide code that
+runs both under Python2 and Python3.
+
+Presenter Notes
+...............
 
-TODO
+python-future is a higher-level compatibility layer than six that includes more backported functionality from Python 3, more forward-ported functionality from Python 2
 
 ----
 
@@ -109,27 +132,24 @@ Why MIT instead of Apache 2.0 ?
 
 ----
 
-Coding convention
-=================
-
-----
-
-Python 2 end of support
------------------------
-
-By 2020, the `support of Python2 will end <https://pythonclock.org/>`_.
-All your projects must be python3 based, supporting Python2 becomes optional.
-
+Coding convention:
+==================
 
-Look at the `developer statistics <https://www.jetbrains.com/research/python-developers-survey-2018/#python-3-adoption>`_
-
-You can use the `six library <https://pypi.python.org/pypi/six>`_ to provide code that
-runs both under Python2 and Python3.
+Set of guidelines for a specific programming language that recommend: programming style, practices, and methods for each aspect of a program written in that language. It contains:
 
-Presenter Notes
-...............
+* File organization, 
+* indentation, 
+* comments, 
+* declarations, 
+* statements, 
+* white space, 
+* naming conventions, 
+* programming practices, 
+* programming principles, 
+* programming rules of thumb, 
+* architectural best practices, 
 
-python-future is a higher-level compatibility layer than six that includes more backported functionality from Python 3, more forward-ported functionality from Python 2
+Why ? reduce cost of software maintenance.
 
 ----
 
@@ -197,16 +217,18 @@ Zen of Python: `PEP20 <https://www.python.org/dev/peps/pep-0020/>`_
 Tools
 -----
 
-* `flake8 <https://pypi.python.org/pypi/flake8>`_
-* `pylint <https://www.pylint.org/>`_
-* `modernize <https://pypi.python.org/pypi/modernize>`_
-* `autopep8 <https://pypi.python.org/pypi/autopep8>`_
-* `landscape.io <https://landscape.io/>`_: `Example <https://landscape.io/github/silx-kit/silx/>`_
-* IDE
+* Use an Integrated Development Environments (IDE) like:
+
+  - `pyCharm <https://www.jetbrains.com/pycharm/>`_ Probably the best IDE for Python
+  - `pyDev <http://www.pydev.org/>`_ Eclipse plugin
 
-  - `pyDev (eclipse) <http://www.pydev.org/>`_
-  - `pyCharm <https://www.jetbrains.com/pycharm/>`_
+* Other tools to improve your code:
 
+  -  `pylint <https://www.pylint.org/>`_: Validation of Python code, syntax, variable names
+  -  `flake8 <https://pypi.python.org/pypi/flake8>`_: Validation of code style (PEP8)
+  -  `modernize <https://pypi.python.org/pypi/modernize>`_: Helps you upgrade to Python3
+  -  `autopep8 <https://pypi.python.org/pypi/autopep8>`_: rewrites your code in PEP8 !
+  
 ---- 
 
 Scafold of a minimalistic Python project
@@ -217,7 +239,9 @@ Scafold of a minimalistic Python project
    pet_project/
        pet_project/
            __init__.py
+           
        LICENSE.txt
        README.txt
+       [requirements.txt]
        setup.py
 

software_engineering/2_Git/index.rst

@@ -8,6 +8,9 @@
    }
    </style>
 
+.. include:: <isonum.txt>
+
+
 GIT
 ===
 
@@ -74,19 +77,20 @@ encourage collaboration using forks of projects.
 The main advantages are:
 
 * simplify contribution.
-* many tutorials for `gitHub <https://guides.github.com/>`_ and `gitlab <https://docs.gitlab.com/ee/gitlab-basics/>`_.
+* many tutorials for `github <https://guides.github.com/>`_ and `gitlab <https://docs.gitlab.com/ee/gitlab-basics/>`_.
 * web page hosting for projects.
 * over the years a cluster of services have pop up to help developers like `Travis <https://github.com/marketplace/travis-ci>`_ and `AppVeyor <https://github.com/marketplace/appveyor>`_).
 * `offer a fixed pipeline based on *Pull request* <https://help.github.com/articles/using-pull-requests/>`_.
-* lead to some 'normalization' of projects.
+* lead to some 'standardization' of projects.
+
 
 ----
 
 github vs gitlab
 ````````````````
 
 * github should bring to your project an `Higher visibility compared to other hosting (in 2017) <http://software.ac.uk/resources/guides/choosing-repository-your-software-project>`_.
-* github is usually one step ahead of gitlab regarding features and usability.
+* github is usually one step ahead compare to gitlab regarding features and usability.
 * activities on github are monitored by head-hunters and can be useful for professional placement.
 * gitlab allows you to select a privacy level for your projects. Public projects can be seen from outside: https://gitlab.esrf.fr/public not private projects.
 * github is free for open-source project.
@@ -98,8 +102,10 @@ github vs gitlab
 Presenter Notes
 ...............
 
-The amount of the acquirement by Microsoft show the importance of github on the today life of the developer.
-As a consequence thousands of project has move from github to gitlab. (50000 after a week)
+* github intend to open itself to services, gitlab intend to embed them. Usage is the same but philosophy is different.
+* The amount of the acquirement by Microsoft show the importance of github on the today life of the developer.
+  As a consequence thousands of project has move from github to gitlab. (50000 after a week)
+* gitlab is free and open source. But has big compamies behind (nas, bayer, siemens...)
 
 ----
 
@@ -117,9 +123,9 @@ git permits several workflows:
 Presenter Notes
 ...............
 
-- centralized : a single point of entry 'central repository'. Let each users to deal with synchronization
-- feature branch workflow: each new feature should take place in a dedicated branch
-- gitflow : strict management of branches designed for releases. One branch per:
+* centralized : a single point of entry 'central repository'. Let each users to deal with synchronization
+* feature branch workflow: each new feature should take place in a dedicated branch
+* gitflow : strict management of branches designed for releases. One branch per:
     - releases
     - each feature
     - fix
@@ -139,13 +145,14 @@ Presenter Notes
 ...............
 
 Why the 'forking flow' ? ==> commonly used. The one of silx for example.
+This schema is very important ant we will follow it during all along training
 The idea is that each developer can interact with other from his own fork.
 Each developer can request to merge some modifications (feature, bug fix...) with others: this is a pull request
 
-- simplify branch forking
-- Always keep upstream branch ready for deployment with features and fixes
-- Each new branch starts from the master (up to date)
-- Use merge request for each new feature
+* simplify branch forking
+* Always keep upstream branch ready for deployment with features and fixes
+* Each new branch starts from the master (up to date)
+* Use merge request for each new feature
 
 ----
 
@@ -197,7 +204,7 @@ Example: create a new git project (2)
 
 .. code-block:: bash
 
-    git remote add origin [email protected]:silx/silx-trainings/pypolynom.git
+    git remote add origin [email protected]:silx/pypolynom.git
 
 7. add files to a commit (detail later)
 
@@ -234,11 +241,10 @@ Hands on: fork an existing project
 
     1.1 login to github / gitlab
 
-    1.2 look for the 'https://gitlab.esrf.fr/silx/silx-trainings/pypolynom_completed' project
+    1.2 look for the 'https://gitlab.esrf.fr/silx/pypolynom' project
 
     1.3 fork the project and go to the homepage of the fork you just created
 
-.. include:: <isonum.txt>
 
 |rarr| This will provide you an url to your personal repository.
 
@@ -257,7 +263,7 @@ Hands on: fork an existing project
 
 .. code-block:: bash
 
-    git clone [email protected]:[my_id]/pypolynom_completed.git
+    git clone [email protected]:[my_id]/pypolynom.git
 
 |rarr| You are now ready for making some modifications and share them with others.
 
@@ -274,15 +280,24 @@ branches
 
 |rarr| Two branches can be merge together.
 
+The case we will consider:
+
 .. image:: images/git_branch.png
     :align: center
+    :width: 50%
 
+A more realistic case:
+
+.. image:: images/branches_real.png
+    :align: center
+    :width: 28%
 
 Presenter Notes
 ```````````````
 
 Eah commit has an 'ID': SHA-1 checksum from modifications + commit message + author + date
 
+To simplify thinks, we will consider the master branch to be the develop branch.
 
 ----
 
@@ -323,6 +338,11 @@ commits with authors, data time, file changed, and the chain of commits called *
 
 .. note:: *graphic tools as* `git-gui <https://git-scm.com/docs/git-gui>`_ *and* `gitk <https://git-scm.com/docs/gitk>`_ *might help you for commits and to have a graphic representation of the tree view.*
 
+Presenter Notes
+```````````````
+
+git add / git commit can be repeated
+
 ----
 
 Some useful git commands
@@ -333,20 +353,21 @@ Some useful git commands
 * *git diff* : show changes between commits
 * *git tag* : add a tag at a specific point of the history
 
-----
-
 Presenter Notes
 ...............
 
 git tag can help you to retrieve some milestone
 git reflog
 
+----
+
 Hands on: propose modifications
 -------------------------------
 
 For this exercise you can use a `git Cheat sheet <https://education.github.com/git-cheat-sheet-education.pdf>`_ if you like.
 
-Now we want to make some modifications on the source code (for a bug fix for example).
+The goal is to make some modifications on the source code (for a bug fix for example).
+
 We need to:
 
 * create a new branch relative to the bug fix
@@ -477,7 +498,7 @@ the one from the other developers.
 
 .. code-block:: bash
 
-    git remote add upstream [email protected]:silx/silx-trainings/pypolynom.git
+    git remote add upstream [email protected]:silx/pypolynom.git
     # git remote add co-worker [email protected]:<co-worker>/pypolynom.git
 
 2. merge those modification on your master branch
@@ -519,3 +540,9 @@ or you might want to contribute to other projects.
 How to contribute to an Open Source project is presented in
 `this document <http://scikit-image.org/docs/stable/contribute.html>`_
 for scikit-image.
+
+
+Presenter Notes
+...............
+
+I hope you where happy to meet your new best friend