|
|
Migration to git
|
|
|
=================
|
|
|
:gecos: GeCoS
|
|
|
:toc:
|
|
|
|
|
|
|
|
|
|
|
|
Introduction
|
|
|
-------------
|
|
|
|
|
|
{gecos} is a large project with a bit less that a thousand eclipse plugins.
|
|
|
So far, it has been handled as one big piece of software:
|
|
|
|
|
|
* One SVN repository used for source code management.
|
|
|
* The whole project is build/deployed at once from sources i.e.
|
|
|
internal dependencies (between {gecos} plugins) are satisfied from sources directly.
|
|
|
|
|
|
Few of the main problems with this approach are:
|
|
|
|
|
|
* Many unused plugins becomes obsolete and pollute the SVN repository. +
|
|
|
When compatibility-breaking modfifications
|
|
|
are performed on other used plugins, we either need to update such plugins
|
|
|
(tedious, time consuming) to be able to build the project or exclude
|
|
|
them from the build, which essentially turns them into zombies.
|
|
|
* The build/test process is long and tedious.
|
|
|
* Plugins Versionning is virtually impossible.
|
|
|
* Branch/Merge operations are very tedious which
|
|
|
|
|
|
To help solving these problems, most active {gecos} plugins from the SVN repository
|
|
|
are being orginized into small groups (per functionality) and moved to independent git
|
|
|
repositories at https://gitlab.inria.fr/gecos[inria Gitlab].
|
|
|
|
|
|
Each group of {gecos} plugins centered arround one (or more) functionality are
|
|
|
bundled into a higher level entity, reffered to as *{gecos} project*.
|
|
|
A {gecos} project is treated as an independent peace of software with:
|
|
|
|
|
|
* proper versioning and dependencies management
|
|
|
* an associated git repository
|
|
|
* a (versioned) _release_ p2 repositoy (eclipse update site) maintained indefinetly
|
|
|
* other short-lived p2 repositories (_snapshot_ and _testing_)
|
|
|
* a build/test/deploy/ Continuous Integration system.
|
|
|
|
|
|
The aim is to ultimately make every {gecos} project
|
|
|
https://en.wikipedia.org/wiki/Continuous_delivery[Continuously deliverable].
|
|
|
|
|
|
|
|
|
Projects decomposition
|
|
|
----------------------
|
|
|
|
|
|
The so far available {gecos} projects are:
|
|
|
|
|
|
gecos-framework
|
|
|
~~~~~~~~~~~~~~~
|
|
|
This project contains the {gecos} Framework including, the compiler eclipse application,
|
|
|
eclipse run/debug configuration, compiler script (.cs) editor, script module/primitive
|
|
|
extension mechanism and other UI functionalities.
|
|
|
|
|
|
----
|
|
|
Dependencies: []
|
|
|
----
|
|
|
|
|
|
gecos-testframework
|
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
This project contains the integration testing framework along with some test resources
|
|
|
(C code applications ...).
|
|
|
|
|
|
----
|
|
|
Dependencies: [gecos-framework]
|
|
|
----
|
|
|
|
|
|
gecos-tools
|
|
|
~~~~~~~~~~~
|
|
|
This is a sub-group with 4 projects providing various external and internal tools:
|
|
|
|
|
|
* *gecos-tools-tomsdk*: wrap external http://tom.loria.fr[TOM] language SDK.
|
|
|
* *gecos-tools-tommapping*: Define an Xtext-based DSL for easily generating
|
|
|
TOM mappings for Ecore/Xcore models.
|
|
|
* *gecos-tools-graph*: wrap external http://jgrapht.org/[JGraphT] library
|
|
|
and provide a generic graph model (IGraph).
|
|
|
* *gecos-tools-emf*: provides various tools related but not restricted to
|
|
|
http://www.eclipse.org/modeling/emf/[Eclipse Modeling Framework (EMF)].
|
|
|
|
|
|
----
|
|
|
Dependencies: [gecos-framework]
|
|
|
----
|
|
|
|
|
|
gecos-core
|
|
|
~~~~~~~~~~
|
|
|
This project contains the CDFG model, the CDT front-end and C code generator.
|
|
|
It is meant to be the minimal set of plugins needed to get a working C-to-C compilation flow.
|
|
|
|
|
|
[WARNING]
|
|
|
==========================
|
|
|
Currently other plugins such as transforms, analysis, utils, dag-adapter...
|
|
|
are included in this project, but these might be separated in the future.
|
|
|
==========================
|
|
|
|
|
|
----
|
|
|
Dependencies: [gecos-framework, gecos-testframework and gecos-tools.]
|
|
|
----
|
|
|
|
|
|
|
|
|
|
|
|
Project Structure
|
|
|
-----------------
|
|
|
|
|
|
At the root directory of a {gecos} project you find the following:
|
|
|
|
|
|
* *bundles/*: contains all the eclipse plugins that constitute the main sources of the project.
|
|
|
* *tests/*: contains one or more eclipse feature project (define groups of eclipse plugins)
|
|
|
* *features/*: contains all the eclipse features (*.feature)
|
|
|
* *releng/*: contains all release related sources, mainly:
|
|
|
** ***.update/**: eclipse update site; defines the set of features/plugins to be included in
|
|
|
the p2 update site, and organize them into categories
|
|
|
** ***.target/**: eclipse http://www.vogella.com/tutorials/EclipseTargetPlatform/article.html[target plateform definition]; defines the dependencies of the project.
|
|
|
+
|
|
|
[IMPORTANT]
|
|
|
==========================
|
|
|
A target definition project named <__name__> must contain a target definition file named <__name__>__.target__. +
|
|
|
e.g.: gecos.target__.target __ if the project name is gecos.target
|
|
|
==========================
|
|
|
* *.mvn/*: contains the https://maven.apache.org/what-is-maven.html[Maven] related settings
|
|
|
such as https://maven.apache.org/settings.html[extensions.xml] file.
|
|
|
* *.gitignore*: contains path patterns that should be ignored by git
|
|
|
* *README.md*: contains various information about the project, its documentation site,
|
|
|
update site, installation procedure ...
|
|
|
* *CHANGELOG.md*: contains release change logs.
|
|
|
It MUST be maintained with each new version release !
|
|
|
* https://maven.apache.org/pom.html[*pom.xml*]: Maven configuration file.
|
|
|
* https://docs.gitlab.com/ee/ci/yaml/[*.gitlab-ci.yml*]: Gitlab CI configuration file.
|
|
|
|
|
|
|
|
|
Naming Convention
|
|
|
~~~~~~~~~~~~~~~~~
|
|
|
The name of a {gecos} project should follow the template: *gecos-<__pname__>* +
|
|
|
where <__pname__> should be:
|
|
|
|
|
|
* very concise description of the main functionality of the project, preferably one word
|
|
|
* should not use uppercase
|
|
|
|
|
|
All sources (bundles, features, tests, releng) in a project shoule be named:
|
|
|
*fr.irisa.cairn.gecos.<__pname*__>.<__suffix__>* +
|
|
|
where:
|
|
|
|
|
|
* <__pname*__> is <__pname__> without any \'-'.
|
|
|
+
|
|
|
--
|
|
|
e.g.: <__pname__>= "test-framework" then <__pname*__> = "testframework"
|
|
|
--
|
|
|
* <__suffix__> must end with ".feature", ".update" and ".target" for feature, update site
|
|
|
and target definition eclipse projects, respectively.
|
|
|
|
|
|
|
|
|
|
|
|
Versioning/Dependencies management
|
|
|
----------------------------------
|
|
|
|
|
|
[[section-versioning, Versioning]]
|
|
|
Versioning
|
|
|
~~~~~~~~~~
|
|
|
Each {gecos} project is considered as an independent, atomic, piece of software.
|
|
|
It can thus evolve independently from other projects.
|
|
|
|
|
|
The version management is performed at the project level. That is,
|
|
|
all bundles/features in a project are considered to have the **SAME** version
|
|
|
even if some remains unchanged between versions.
|
|
|
This is in order to simplify the versioning procedure and avoid the hassle of properly
|
|
|
versioning every eclipse project independently.
|
|
|
|
|
|
The versioning follows the http://semver.org[Semantic Versioning Specification].
|
|
|
In short, a version number is composed of *MAJOR.MINOR.PATCH*, where:
|
|
|
|
|
|
* *MAJOR* is incremented when making incompatible API changes
|
|
|
* *MINOR* is incremented when adding functionality in a backwards-compatible manner
|
|
|
* *PATCH* is incremented when making backwards-compatible bug fixes.
|
|
|
|
|
|
|
|
|
Dependencies
|
|
|
~~~~~~~~~~~~
|
|
|
The set of all dependencies (including to other {gecos} projects) needed to
|
|
|
build a {gecos} project are specified using an
|
|
|
https://wiki.eclipse.org/PDE/Target_Definitions[eclipse target definition file]
|
|
|
named "<__prefix__>.target.target" located at "/releng/<__prefix__>.target"
|
|
|
in the project's sources repository.
|
|
|
|
|
|
WARNING: Only p2 repositories must be used in the target definition file to specify dependencies.
|
|
|
|
|
|
Internal dependencies (i.e. between {gecos} projects) are resolved through
|
|
|
artifacts distributed on their associated update sites (p2 reposiories).
|
|
|
This enforces the boundaries between {gecos} projects and allow each project
|
|
|
to evolve independently without breaking other projects.
|
|
|
|
|
|
For instance, a dependency to another {gecos} project <__pname2__> at version <__X.Y.Z__>
|
|
|
MUST be specified in the target definition file from its update site with the proper version number: +
|
|
|
<__siteURL__>/gecos/<__pname2__>/release/<__X.Y.Z__>/
|
|
|
|
|
|
WARNING: DO NOT use the latest version link !
|
|
|
This ensures that each project can safely evolve independently from other {gecos} projects without breaking other dependent projects.
|
|
|
|
|
|
To ensure to correct functionning, the new {gecos} update site structure must be handles with extreme cautiousness.
|
|
|
Always back it up before doing any manipulation.
|
|
|
Be careful in case you want to perform a restructuring of the update site, In this case you need to keep in mind and properly modify the target definition files of all projects.
|
|
|
|
|
|
<<section-update-site, Update site section>>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[[section-update-site, Update site]]
|
|
|
{gecos} Update Site (p2 repository)
|
|
|
-----------------------------------
|
|
|
|
|
|
The gecos update site is currently hosted at (`<siteURL>`):
|
|
|
http://gecos.gforge.inria.fr/updatesite/ .
|
|
|
|
|
|
It contains an entry per {gecos} project.
|
|
|
The one associated with the project "gecos-<__name__>" is located at: `<siteURL>/gecos/<name>/`
|
|
|
and is structured as follows:
|
|
|
|
|
|
* *release/*: contains all released versions (kept for a very long time)
|
|
|
** *<__version__>/*: one release version (see <<section-versioning, Versioning>>)
|
|
|
** *latest/*: link to the latest release version
|
|
|
|
|
|
* *snapshot/*: contains in-between releases develop snapshots (kept at least til the second next release)
|
|
|
** *<__timestamp__>/*: Europe/Paris UTC snapshot build date in `YYYYMMDDhhmmss` format
|
|
|
** *latest/*: link to the latest snapshot version
|
|
|
|
|
|
* *testing/*: contains temporary snapshots (can be removed at anytime!)
|
|
|
** *<__timestamp__>/*: Europe/Paris UTC snapshot build date in `YYYYMMDDhhmmss` format
|
|
|
** *latest/*: link to the latest testing version
|
|
|
|