Bug 478312 - [SysML 1.4][doc] add a minimal documentation to help
external contributions
Change-Id: I55df22fad5589615a6cd251b3f6685956ff132bb
Task-Url: https://bugs.eclipse.org/bugs/show_bug.cgi?id=478312
Signed-off-by: Francois Le Fevre - CEA <francois.le-fevre@cea.fr>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d997f84..1097a0e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,7 +6,7 @@
Project description:
--------------------
-A DSML for the [SysML 1.4 OMG](http://www.omg.org/spec/SysML/1.4/Beta/) norm based upon the [Eclipse Papyrus project](https://projects.eclipse.org/projects/modeling.mdt.papyrus).
+A DSML for the [SysML 1.4 OMG](http://www.omg.org/spec/SysML/1.4/) norm based upon the [Eclipse Papyrus project](https://projects.eclipse.org/projects/modeling.mdt.papyrus).
Create a new [bug](https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Papyrus&component=SysML):
-----------------
diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml
new file mode 100644
index 0000000..d957172
--- /dev/null
+++ b/src/site/fml/faq.fml
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<faqs xmlns="http://maven.apache.org/FML/1.0.1"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
+ title="Frequently Asked Questions"
+ toplink="false">
+
+ <part id="general">
+ <title>General</title>
+
+ <faq id="get-code">
+ <question>
+ Where to retrieve the code?
+ </question>
+ <answer>
+ <p>You have to clone the git repository</p>
+ <source>git clone https://git.eclipse.org/r/papyrus/org.eclipse.papyrus-sysml</source>
+ </answer>
+ </faq>
+
+ <faq id="get-website">
+ <question>
+ Where is the website of the project?
+ </question>
+ <answer>
+ <p>You have to go <a href="https://hudson.eclipse.org/papyrus/view/Sysml/job/papyrus-sysml-website/ws/site-staging/index.html">https://hudson.eclipse.org/papyrus/view/Sysml/job/papyrus-sysml-website/ws/site-staging/index.html</a></p>
+ </answer>
+ </faq>
+
+ <faq id="get-javadoc">
+ <question>
+ Where is the javadoc of the project?
+ </question>
+ <answer>
+ <p>You have to go <a href="https://hudson.eclipse.org/papyrus/view/Sysml/job/papyrus-sysml-website/ws/site-staging/apidocs/index.html">https://hudson.eclipse.org/papyrus/view/Sysml/job/papyrus-sysml-website/ws/site-staging/apidocs/index.html</a></p>
+ </answer>
+ </faq>
+
+ <faq id="get-hudson">
+ <question>
+ Where are the continuous integration jobs?
+ </question>
+ <answer>
+ <p>You have to go <a href="https://hudson.eclipse.org/papyrus/view/Sysml/">https://hudson.eclipse.org/papyrus/view/Sysml/</a></p>
+ </answer>
+ </faq>
+
+ <faq id="get-gerrit">
+ <question>
+ Where is the review server?
+ </question>
+ <answer>
+ <p>You have to go to gerrit: <a href=" https://git.eclipse.org/r/#/q/status:open+project:papyrus/org.eclipse.papyrus-sysml"> https://git.eclipse.org/r/#/q/status:open+project:papyrus/org.eclipse.papyrus-sysml</a></p>
+ </answer>
+ </faq>
+
+ </part>
+
+ <part id="install">
+
+ <title>Installation</title>
+
+ <faq id="how-install">
+ <question>
+ How do I install SysML?
+ </question>
+ <answer>
+ <p>SysMl 1.4 is an eclipse project and follow the standard recommendation of the Eclipse Foundation for installation.</p>
+ </answer>
+ </faq>
+
+ </part>
+
+</faqs>
\ No newline at end of file
diff --git a/src/site/pdf/developer-guide.pdf.xml b/src/site/pdf/developer-guide.pdf.xml
index 3c609cb..c833250 100644
--- a/src/site/pdf/developer-guide.pdf.xml
+++ b/src/site/pdf/developer-guide.pdf.xml
@@ -11,9 +11,11 @@
<toc name="Table of Contents">
<item name="Introduction" ref="index.html"/>
<item name="Developer" ref="developer/home.html"/>
- <item name="Norm requirement extraction" ref="developer/normRequirementExtraction.html"/>
- <item name="Generation from Norm to code and configuration files" ref="developer/toolGenerationSOP.html"/>
- <item name="Adding operations to the norm" ref="developer/upgradingNorm.html"/>
+ <item name="SOP1 Norm requirement extraction" ref="developer/sop1-normRequirementExtraction.html"/>
+ <item name="SOP2 Generation from Norm to code and configuration files" ref="developer/sop2-toolGeneration.html"/>
+ <item name="SOP3 Adding operations to the norm" ref="developer/sop3-upgradingNorm.html"/>
+ <item name="SOP4 Requirement" ref="developer/sop4-requirement.html"/>
+ <item name="FAQ" ref="faq.html"/>
</toc>
<cover>
diff --git a/src/site/resources/img/developer/sop4-requirement/derivereqt.png b/src/site/resources/img/developer/sop4-requirement/derivereqt.png
new file mode 100644
index 0000000..5650217
--- /dev/null
+++ b/src/site/resources/img/developer/sop4-requirement/derivereqt.png
Binary files differ
diff --git a/src/site/resources/img/developer/sop4-requirement/omg-requirement.png b/src/site/resources/img/developer/sop4-requirement/omg-requirement.png
new file mode 100644
index 0000000..a67798d
--- /dev/null
+++ b/src/site/resources/img/developer/sop4-requirement/omg-requirement.png
Binary files differ
diff --git a/src/site/xdoc/developer/home.xml b/src/site/xdoc/developer/home.xml
index 0c770fa..482c3de 100644
--- a/src/site/xdoc/developer/home.xml
+++ b/src/site/xdoc/developer/home.xml
@@ -8,10 +8,80 @@
<body>
<section name="Developer">
- <p>section dedicated for </p>
+ <p>This section is dedicated for developers. It should be the main entry point.</p>
</section>
- <section name="Life Cycle Management">
+ <section name="Requirements">
+ <subsection name="Eclipse">
+ <p>Use Eclipse, at least Mars version</p>
+ </subsection>
+ <subsection name="Maven">
+ <p>Use Maven 3.3.1 at least</p>
+ </subsection>
+ <subsection name="Eclipse plugins">
+ <p>Install M2e plugin in your Eclipse</p>
+ <p>Install Tycho Configurator as an additional maven connector</p>
+ <p>No specific extra from papyrus</p>
+ </subsection>
+ <subsection name="SysML">
+ <p>
+ Have a look to the normative document of OMG:
+ <a
+ href="https://hudson.eclipse.org/papyrus/view/Sysml/job/papyrus-sysml-website/ws/target/site/norm/ptc-13-12-10.pdf#3">Embedded norm</a>
+ </p>
+ </subsection>
+
+ <subsection
+ name="Check your installation by a basic checkout, compilation">
+ <ul>
+ <li>
+ Clone the sysml 14 git repository git clone
+ https://git.eclipse.org/r/papyrus/org.eclipse.papyrus-sysml.
+ </li>
+ <li>
+ Run maven at the root of the repo: mvn clean install; it should
+ pass
+ </li>
+ <li>
+ Get sysml14 plugins in your eclipse workspace
+ </li>
+ <li>Et “Voila” you are good to go.</li>
+ </ul>
+ </subsection>
+ </section>
+
+ <section
+ name="Example of a minimal iteration: from bug, to requirement, to code integration through gerrit review.">
+ <ul>
+ <li>
+ Describe in Bugzilla the bug, feature you are working on.
+ Please
+ use the component SysML. And begins with [SysML 1.4] for
+ Summary.
+ </li>
+ <li>
+ Get the code from the master with git,git clone
+ https://git.eclipse.org/r/papyrus/org.eclipse.papyrus-sysml, and
+ work on a local
+ branch,
+ </li>
+ <li>
+ Add the new requirement in the different sysml 1.1 models located
+ in the doc folder of the relevant plugin. have a look to
+ <a href="sop4-requirement.html">SOP4: Requirement</a>
+ </li>
+ <li>Modify the code</li>
+ <li>Push on Gerrit
+ ssh://{ECLISPEUSERLOGIN}@git.eclipse.org:29418/papyrus/org.eclipse.papyrus-sysml
+ </li>
+ <li>Ask for a review https://git.eclipse.org/r/#/dashboard/self</li>
+ <li>After a few iteration, you code should be merged and accessible
+ in the master.
+ </li>
+ </ul>
+ </section>
+
+ <section name="Product Life Cycle Management with Maven">
<subsection name="Run a default installation">
<source>mvn clean install
</source>
@@ -28,36 +98,27 @@
</subsection>
</section>
- <section name="Requirements">
- <subsection name="Eclipse">
- <p>Use Eclipse, at least Mars version</p>
- </subsection>
- <subsection name="Maven">
- <p>Use Maven 3.3.1 at least</p>
- </subsection>
- <subsection name="Eclipse plugins">
- <p>Install M2e plugin in your Eclipse</p>
- <p>Install Tycho Configurator as an additional maven connector</p>
- </subsection>
- <subsection name="SysML">
- <p>Have a look to the normative document of OMG: <a href="https://hudson.eclipse.org/papyrus/view/Sysml/job/papyrus-sysml-website/ws/target/site/norm/ptc-13-12-10.pdf#3">Embedded norm</a>
- </p>
- </subsection>
- </section>
+
<section name="Standard Operating Procedures">
<ul>
<li>
- <a href="normRequirementExtraction.html">Norm requirements extractions</a>
+ <a href="sop1-normRequirementExtraction.html">SOP1: OMG Norm requirements automanual extraction</a>
</li>
<li>
- <a href="toolGenerationSOP.html">Tool generation SOP</a>
+ <a href="sop2-toolGeneration.html">SOP2: From a OMG profile to a dedicated Papyrus
+ application (elementype, palette etc...)
+ </a>
</li>
<li>
- <a href="upgradingNorm.html">Adding a new operation to the norm profile</a>
+ <a href="sop3-upgradingNorm.html">SOP3: Extended the norm by adding a new operation.</a>
+ </li>
+ <li>
+ <a href="sop4-requirement.html">SOP4: Add a new requirement.</a>
</li>
</ul>
</section>
+
</body>
</document>
\ No newline at end of file
diff --git a/src/site/xdoc/developer/normRequirementExtraction.xml b/src/site/xdoc/developer/sop1-normRequirementExtraction.xml
similarity index 100%
rename from src/site/xdoc/developer/normRequirementExtraction.xml
rename to src/site/xdoc/developer/sop1-normRequirementExtraction.xml
diff --git a/src/site/xdoc/developer/toolGenerationSOP.xml b/src/site/xdoc/developer/sop2-toolGeneration.xml
similarity index 100%
rename from src/site/xdoc/developer/toolGenerationSOP.xml
rename to src/site/xdoc/developer/sop2-toolGeneration.xml
diff --git a/src/site/xdoc/developer/upgradingNorm.xml b/src/site/xdoc/developer/sop3-upgradingNorm.xml
similarity index 82%
rename from src/site/xdoc/developer/upgradingNorm.xml
rename to src/site/xdoc/developer/sop3-upgradingNorm.xml
index a04a9d0..9ea2874 100644
--- a/src/site/xdoc/developer/upgradingNorm.xml
+++ b/src/site/xdoc/developer/sop3-upgradingNorm.xml
@@ -19,15 +19,15 @@
<p>Add your new operations here:
/org.eclipse.papyrus.sysml14/doc/SysML-Extension.di
</p>
- <p>Open it with UML Editor to access UML type and cardinality</p>
- <p>Add your requirements here by creating a new derive requirement with Papyrus Req plugin:
+ <p>Open it with UML Editor to access UML type</p>
+ <p>Add your requirements here:
/org.eclipse.papyrus.sysml14/doc/org.eclipse.papyrus.sysml14.di
</p>
</subsection>
<subsection name="SysML profile: semantic upgrade">
<p>Modify
/org.eclipse.papyrus.sysml14/resources/profile/SysML.profile.uml to
- add a new operation, with its parameters.
+ add a new operation.
</p>
<p>Open the genmodel and reload the UMl profile and regenerate the
code.
@@ -35,21 +35,18 @@
<p>validation you enhance code should be in
/org.eclipse.papyrus.sysml14/src-gen
</p>
- <p>Implement the function in the /org.eclipse.papyrus.sysml14/src; do not forget to reference the requirement
+ <p>Implement the function in the /org.eclipse.papyrus.sysml14/src
</p>
</subsection>
<subsection name="SysML diagram upgrade">
<p>Modify the Expansion diagram of your
/org.eclipse.papyrus.sysml14.diagram.blockdefinition/resources/configuration/blockDefinitionDiagramConfig.expansionmodel
</p>
- <p>Add new representation, a new induced representation and do not forget to add it to the context.</p>
- <p>becarefull the editor replace all platform:/plugin by a ../.../.. </p>
</subsection>
<subsection name="SysML element type">
<p>/org.eclipse.papyrus.sysml14.diagram.common/resources/SysML14ClassDiagram-extension.elementtypesconfigurations
</p>
- <p>Add a new Specialization type configuration and eventually its edit helper</p>
</subsection>
<subsection name="Palette">
<p>Add your element in the palette:
diff --git a/src/site/xdoc/developer/sop4-requirement.xml b/src/site/xdoc/developer/sop4-requirement.xml
new file mode 100644
index 0000000..a0403de
--- /dev/null
+++ b/src/site/xdoc/developer/sop4-requirement.xml
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+
+ <properties>
+ <title>SysML - Tools Generation Standard Operating Procedure</title>
+ </properties>
+
+ <body>
+ <section name="Context">
+ <p>In order to develop the SysML 1.4 application, the developer team
+ has choosen to use a model based approach.
+ At least, it is used to gather all requirements in different SysML 1.1
+ models.
+ </p>
+ <p>A first model of requirement has been made by extracting all basic
+ requirements from the Norm. Each section of the norm described in
+ the table of content has been extracted as a requirement.</p>
+ <p>This model is located here core/org.eclipse.papyrus.sysml14/doc/omg.sysml.uml
+ </p>
+ <p>New requirements, through the use of papyrus Req plugin, are
+ created in each SysML 1.1 model located in the doc folder of each
+ module. They should use the "DeriveReqt" link.</p>
+ <p>Finaly you could reference your requirement anywhere in your code, document by using the following convention:</p>
+ <source>@pap.req ${Model.ID}#{Req.ID}</source>
+ <p>The goal is to have a tool, plugin that will be able to parse this snipped of code to link it to the model, and eventually open the model.</p>
+ </section>
+
+ <section name="Example">
+ <subsection name="Zoom on OMG SYSML Requirement Model">
+ <p>Pay attention to the ID, NAME and the TEXT, that have been
+ normalized.</p>
+ <img alt="omg" src="img/developer/sop4-requirement/omg-requirement.png" />
+ </subsection>
+ <subsection name="Zoom on a Derivereq Link">
+ <p>Pay attention to the ID, it has to be uniq, it is generated by the Papyrus Req plugin: /org.eclipse.papyrus/extraplugins/req/org.eclipse.papyrus.req.reqif</p>
+ <p>Papyrus Req plugin is an extra plugin of Papyrus project, you have to download it and install it in your own Eclipse instalaltion. Then when opening a requirment diagram, you will have a new right-click menu thta allows you to create directly new derived requirement from an initial requirement. It will compute automatically the identifier and pre-fill the text.</p>
+ <img alt="derivereqt" src="img/developer/sop4-requirement/derivereqt.png" />
+ </subsection>
+ </section>
+
+ </body>
+
+</document>
\ No newline at end of file
