.. Getting started - Emencia documentation master file, created by
   sphinx-quickstart on Sun Nov 15 11:44:57 2015.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. _Emencia: https://www.emencia.com/
.. _Extranet website: https://extranet.emencia.net/
.. _our Gitlab: http://git.emencia.net/
.. _Issue Tracker: http://tracker.emencia.net
.. _Gravatar: http://www.gravatar.com

.. _Django: http://www.djangoproject.com/
.. _Python 2.x: https://docs.python.org/2/
.. _Buildout: http://www.buildout.org/
.. _Epaster: http://epaster.readthedocs.org/
.. _cookiecutter-djangocms3-buildout: https://cookiecutter-djangocms3-buildout.readthedocs.io/

.. _virtualenv: http://www.virtualenv.org/
.. _Sass: http://sass-lang.com/documentation/
.. _Boussole: https://boussole.readthedocs.io
.. _Compass: http://compass-style.org/
.. _Foundation for site: http://foundation.zurb.com/
.. _Django CMS: https://www.django-cms.org/
.. _Django Blog Zinnia: https://github.com/Fantomas42/django-blog-zinnia
.. _Django CKEditor: https://github.com/divio/djangocms-text-ckeditor/
.. _Django Filebrowser: https://github.com/wardi/django-filebrowser-no-grappelli
.. _Optimus: http://optimus.readthedocs.org/
.. _Jinja2: http://jinja.pocoo.org/
.. _Slack: http://slack.com

.. _Django templates: https://docs.djangoproject.com/en/1.8/#the-template-layer

.. _emencia-sphinx: https://git.emencia.net/emencia-projects/emencia-sphinx/blob/master/README.rst
.. _Sentry: http://sentry.emencia.net

.. image:: /_static/logo.png

Getting started to Emencia
==========================

**Welcome to** `Emencia`_,

This is an introduction to get started on our structure and technologies where you can find some usefull links and short explanations.

Internal
********

Communication
-------------


**Every Emencia workmates are connected on** `Slack`_ during worked hours on team ``emencia-group``.

Also you will be given a personal email on ``@emencia.com`` domain.

**Allways paste code and errors** on a `Paster <http://pastebin.com/>`_ `service <http://pastebin.ubuntu.com//>`_ when you ask for help.

.. NOTE::
    We still keep a safeback on IRC channel ``#ecs`` on server ``irc.freenode.net``.

Extranet
--------

We have an `Extranet website`_ for our internal information. You should have been given a new account on Extranet, if not ask for it to someone.

The most important Extranet services are:

Datebook
    To fill your planning and write your worked hours, extra hours and vacations. **Dont forget about it** as this is used at the end of each month to calculate your pay slip.
Forum
    To communicate on internal stuff and especially there is a thread *Emploi du temps > Demande de congé* to **ask for vacation**.
Documents
    Contains **informations about users, customers, etc..** In the end, most informations should be migrated to the *Bazar* service.

.. NOTE::
    Each user has an account avatar image using `Gravatar`_ and your registred email account. Register your email on `Gravatar`_ website to use your own image instead of the automatically generated one.


Tracker
-------

Probably one of our tools you will use most of the time is our `Issue Tracker`_ that you should have been given access to (if not, ask for it).

Once given access with a personal account, you will find all your assigned tickets on a link like this: ::

    http://tracker.emencia.net/?since=120&statuses:list=User

Where ``User`` is your account username (case sensitive). You should bookmark this so you won't never lose any ticket.

.. NOTE::
    You can find a `quick Tracker tutorial <http://academy.emencia.net/2013/03/11/utiliser-le-tracker-emencia/>`_ into our *Academy* site.


Git flow
********

We use a Git flow based on **branches**, **merge requests** and **automatic update deployment**.

#. Commonly you will never work directly on master branch, instead you will create your own new branch for every task or issues;
#. When your work is stable enough to be released, push your branch and go to the gitlab project to create a new Merge request;
#. Merge request will trigger a service that will perform some check about code;
#. You may wait some minutes before check service validate or not your commits;
#. When it's ok, you can use the **Accept merge request** button, it will merge your commit into the master branch and perform automatic deployment;


.. WARNING::
    When your work has been merged, you will need to update your local repository to include the merge from master branch, usually with something like this: ::

        git fetch && git rebase origin/master

    Only then after you can continue to work else your branch can be broken and futher merge request may be refused or even broke the master branch.

.. NOTE::
    This flow is rarely effective on project created before 2016. In this case, you will still work on your own branch but merge it directly into master before pushing everything. Automatic deployment won't be available and you will have to ask to Builtex team for integration or production updates.


Coding
******

We mostly develop on `Python 2.x`_ with `Django`_. Projects are stored into `our Gitlab`_, some of us may `have <https://git.emencia.net/snippets/4>`_ `usefull <https://git.emencia.net/s/slothy>`_ `snippets <https://git.emencia.net/s/sveetch>`_. And eventually we have a public `Github organization <https://github.com/emencia>`_ where is stored all our public applications repositories.

Almost all projects use `Buildout`_ to perform project deployment on multiple environment in a convenient way for Linux and OSX systems.

All our `Django`_ projects are using a common structure allready configured for our common used technologies (Apps, Webdesign stuff, Nginx support, Monit support, etc..). Previously we used `Epaster`_ (you may see some old projects with it), now deprecated in profit of `cookiecutter-djangocms3-buildout`_.

Default database type for project is **Sqlite3** for development and integration environment. And Postgresql for production.

Finally in some rare cases when you need to build static pages without of a Django project, you can see at `Optimus`_ that allows you to build pages using `Jinja2`_ templates (almost the same than Django templates) and optionally some Python code.

.. WARNING::
    Please, write some useful comments in your code, think about those ones which could have to fix or change something after you.

Webdesign
*********

Since we are using Django, most of all **templating** integrations is done with `Django templates`_.

All our **CSS** are writed under `Sass`_ syntax, compiled with `Boussole`_ and packaged with a `Django app <https://github.com/miracle2k/django-assets/>`_.

**Javascript** apps is commonly writed as it and just packaged with the same Django app than for CSS.

Almost all our project integration is done on top of the `Foundation for site`_ framework (currently on `last 5.x version <http://foundation.zurb.com/sites/docs/v/5.5.3/>`_).

.. NOTE::
    There is a slideshow `introduction about Integration <http://emencia.org/sveetch/integration_with_django/>`_ stuff and another to go `much deeper in CSS integration <http://emencia.org/sveetch/scss_compass/>`_. (Be patient, these pages are a bit slow to load)

.. NOTE::
    Our Cookiecutter template documentation contains most of `all informations you need to install Integration stuff <https://cookiecutter-djangocms3-buildout.readthedocs.io/en/latest/topics.html>`_.

.. NOTE::
    We previously used `Compass`_ to compile Sass sources, you may not be able to use `Boussole`_ on old projects (created before 2016) because of their usage of the Compass Sass framework usage.

Deployment
**********

Website projects follow the same usual pattern:

#. Opening project repository on `our Gitlab`_;
#. Creating project structure and first commit using `cookiecutter-djangocms3-buildout`_;
#. Developing project into personal local development environment;
#. Installing project on an acceptance server (also often called "integration" or "development" or even "recette") using project integration deployment;
#. Validating project with customer;
#. Finally installing project on production server using the project production deployment;

During project support time, we follow again these rules starting from acceptance part for each issue.

**We never code directly on acceptance server or production server**.

.. NOTE::
    Acceptance and production projets installs and updates are managed from people from internal group named *Builtex*.

Going further
*************

* If you mind about writing some documentation, we have `emencia-sphinx`_ repository which is installed on http://docs.emencia.net/, you can add new documentation to it using the described procedure in its README;
* We have a `Sentry`_ service that is used for some projects;
* During integration you may need of image placeholder like `FPOImg <http://fpoimg.com/>`_ or `Placehold.it <http://placehold.it/>`_;
* In our Sass sources we are `naming <http://chir.ag/projects/name-that-color/>`_ `colors <http://www.color-hex.com/color-names.html>`_ in variables;
* Damned you need to build a Regex, you `can <http://www.regextester.com/>`_ `use <https://regex101.com/>`_ `some <http://www.pyregex.com/>`_ `help <http://pythex.org/>`_;
* All our documentations, project README, etc.. are written in ReStructuredText syntax, you can use `Online reStructuredText editor <http://rst.ninjs.org/>`_ to valid your document before releasing it;
* Most of projects are using Webfont to embed icons, we have a Professional account on `Icomoon service <https://icomoon.io/app/>`_ to share all projects webfont, ask for it if needed;
* Also we often use `Google fonts <https://www.google.com/fonts/>`_ for fonts and sometime `Typekit <https://typekit.com/fonts>`_ (we should have a professional account on this);
* Some workmates are working on MacOSX systems, think about them, they may need to install your projects to do some work;
* Don't release project with static images that are not optimized, install some tool like ``pngquant`` or ``jpegoptim`` using conservative options to process your images before to commit;