Commit a1b11222 authored by Dennis Hendriks's avatar Dennis Hendriks
Browse files

#73 Dev docs: developer -> development (more renames).

parent 1a478bf5
......@@ -16,12 +16,12 @@
// Defining an alternative 'imgsdir' attribute avoids this problem and images will be visible in the preview.
// For specific parts of the documentation, we introduce an additional attribute, to allow shorter relative paths.
// Changes to attributes require a restart of Eclipse to become effective in the asciidoc editor.
ifndef::imgsdir[:developer-imgsdir: ../images/developer]
ifdef::imgsdir[:developer-imgsdir: {imgsdir}/developer]
ifndef::imgsdir[:development-imgsdir: ../images/development]
ifdef::imgsdir[:development-imgsdir: {imgsdir}/development]
// Defining a unique prefix for all sections in this part of the documentation to avoid duplication of reference ids.
// Note that this only works for section ids and not for figures, tables, etc. (and there is no alternative attribute for this).
:idprefix: developer-
:idprefix: development-
:idseparator: -
:listing-caption: Listing
......
......@@ -19,14 +19,14 @@ indexterm:[Jenkins]
indexterm:[test]
indexterm:[JUnit]
[[developer-building-and-testing-chapter-index]]
[[development-building-and-testing-chapter-index]]
== Building and testing
The Eclipse ESCET software can be built using Maven/Tycho.
The build will build every individual plugin and feature, as well as the update site, product and all documentation.
Manually run it in one of the following ways:
* In an Eclipse-based <<developer-dev-env-setup-chapter-index,development environment>>, select menu:Run[Run Configurations...] to open the _Run Configurations_ dialog.
* In an Eclipse-based <<development-dev-env-setup-chapter-index,development environment>>, select menu:Run[Run Configurations...] to open the _Run Configurations_ dialog.
From the list at the left, under _Maven Build_, select the _build_ launch configuration, and click the btn:[Run] button to run the build.
+
Additional launch configurations are available to build documentation projects separately.
......
......@@ -15,10 +15,10 @@ include::_part_attributes.asciidoc[]
indexterm:[Checkstyle]
indexterm:[formatting]
[[developer-coding-standards-chapter-index]]
[[development-coding-standards-chapter-index]]
== Coding standards
The Eclipse ESCET <<developer-dev-env-setup-chapter-index,development environment>> has some features that allow developing high quality contributions:
The Eclipse ESCET <<development-dev-env-setup-chapter-index,development environment>> has some features that allow developing high quality contributions:
* A Java formatter profile is included.
It allows to automatically format Java code for consistency and convenience.
......@@ -34,7 +34,7 @@ For all contributions to the Eclipse ESCET project, check the following:
* All contributions should be free of warnings and errors, when working with them in the Eclipse ESCET development environment.
Remember that <<developer-contributing-chapter-index,contributions>> are always welcome, and contributions don't have to be perfect.
Remember that <<development-contributing-chapter-index,contributions>> are always welcome, and contributions don't have to be perfect.
The project's developers can help to improve your contribution, and ensure it adheres to these coding standards.
For any questions regarding these coding standards, please <<developer-chapter-index,contact>> the project's developers.
For any questions regarding these coding standards, please <<development-chapter-index,contact>> the project's developers.
......@@ -15,7 +15,7 @@ include::_part_attributes.asciidoc[]
indexterm:[contributing]
indexterm:[patches]
[[developer-contributing-chapter-index]]
[[development-contributing-chapter-index]]
== Contributing
Thanks for your interest in Eclipse Supervisory Control Engineering Toolkit (Eclipse ESCET) project.
......@@ -23,19 +23,19 @@ We welcome your contributions.
The following topics are discussed:
* <<developer-contributing-contribute>>
* <<developer-contributing-keep-sync-official-repo>>
* <<developer-contributing-collab-committers>>
* <<developer-contributing-become-committer>>
* <<development-contributing-contribute>>
* <<development-contributing-keep-sync-official-repo>>
* <<development-contributing-collab-committers>>
* <<development-contributing-become-committer>>
[[developer-contributing-contribute]]
[[development-contributing-contribute]]
=== How to contribute to Eclipse ESCET
It is often a good idea to first discuss your contribution with the project's community and committers, before creating the actual code (e.g. patches), documentation, etc of your contribution.
Discussions can take place via an <<developer-issue-tracking-chapter-index,issue>> in the issue tracker, or on the project's <<developer-chapter-index,'dev' list>>.
Discussions can take place via an <<development-issue-tracking-chapter-index,issue>> in the issue tracker, or on the project's <<development-chapter-index,'dev' list>>.
To contribute your actual contribution, e.g. code, documentation, examples, or anything else to the project, please make sure an issue already exists or create a new issue for it in the <<developer-issue-tracking-chapter-index,issue tracker>>.
To contribute your actual contribution, e.g. code, documentation, examples, or anything else to the project, please make sure an issue already exists or create a new issue for it in the <<development-issue-tracking-chapter-index,issue tracker>>.
To create issues, reply to issues, contribute patches and merge requests, etc, you need an Eclipse Foundation account.
It can easily be created at https://accounts.eclipse.org/user/register.
......@@ -57,7 +57,7 @@ This creates a fork of the official repository under your own account.
** Click the _Clone_ button near the top-right of the page and observe the `https` URL.
** Follow the <<developer-dev-env-setup-chapter-index,development environment setup>> instructions to set up a properly configured development environment.
** Follow the <<development-dev-env-setup-chapter-index,development environment setup>> instructions to set up a properly configured development environment.
You need the `https` URL of your fork for this.
* Make your changes in the forked repository under your own account:
......@@ -72,7 +72,7 @@ To create branches in your fork, navigate to `+https://gitlab.eclipse.org/<usern
There click _New branch_ to create a new branch from `develop`.
** Please start each commit message with the issue number, e.g. `#NNN Commit summary.` for issue `NNN`.
See our <<developer-development-process-chapter-index,development process>> for more information.
See our <<development-development-process-chapter-index,development process>> for more information.
* Once you've finished work on your contribution, create a merge request for it:
......@@ -113,7 +113,7 @@ For more information, including the specific format of commit messages, please s
* link:https://www.eclipse.org/projects/handbook/#resources-commit[Git Commit Records]
A contribution by a non-committer will be reviewed by the project committers.
This includes adherence to the project's <<developer-coding-standards-chapter-index,coding standards>>.
This includes adherence to the project's <<development-coding-standards-chapter-index,coding standards>>.
Discussions regarding the contribution will typically take place in the associated merge request (or issue).
Align with the project committers on who will address the review feedback.
......@@ -125,13 +125,13 @@ Remember that contributions are always welcome, and contributions don't have to
The project's developers can help to improve your contribution.
If you need any help regarding the content of your contribution, the steps above, or anything else, just ask the project's developers via the issue or the project's <<develop-dev-list,'dev' list>>.
See for more information our <<developer-development-process-chapter-index,development process>>.
See for more information our <<development-development-process-chapter-index,development process>>.
[[developer-contributing-keep-sync-official-repo]]
[[development-contributing-keep-sync-official-repo]]
=== Keeping in sync with the official Eclipse ESCET GitLab repository
If you've <<developer-dev-env-setup-chapter-index,set up a development environment>> for your forked repository, it will at some point get out of sync with new developments on the official Eclipse ESCET GitLab repository.
If you've <<development-dev-env-setup-chapter-index,set up a development environment>> for your forked repository, it will at some point get out of sync with new developments on the official Eclipse ESCET GitLab repository.
To sync those changes to your forked repository and to the local clone of your forked repository, follow these steps:
* Navigate in a command prompt or shell to your local Git clone of your forked repository.
......@@ -168,7 +168,7 @@ You are then back in sync and ready to start work on your next contribution.
Using this process it is also possible to work on multiple contributions at once, via separate feature branches.
[[developer-contributing-collab-committers]]
[[development-contributing-collab-committers]]
=== Collaborating with project committers on a contribution
During a review of your contribution, the project committers may provide some feedback on how to improve your contribution.
......@@ -187,7 +187,7 @@ This process also works if multiple contributors are involved.
Some alignment between all parties involved is typically desired to e.g. prevent merge conflicts.
[[developer-contributing-become-committer]]
[[development-contributing-become-committer]]
=== How to become a committer
The Eclipse Foundation operates on the principle of meritocracy.
......
......@@ -12,7 +12,7 @@
include::_part_attributes.asciidoc[]
[[developer-dev-env-setup-chapter-index]]
[[development-dev-env-setup-chapter-index]]
== Development environment setup
Follow these instructions to set up an Eclipse ESCET development environment.
......@@ -69,7 +69,7 @@ The new development environment will be put at `<root_installation_folder>/<inst
** Fill in the _Eclipse ESCET Git clone URL_:
*** Committers with write access to the Eclipse ESCET official GitLab repository can use the default URL `https://gitlab.eclipse.org/eclipse/escet/escet.git`.
*** Contributors can use the same URL, but as they don't have write access, they will not be able to push to the remote repository.
They can instead make a fork of the official Git repository, as described in the <<developer-contributing-chapter-index,contributing>> section.
They can instead make a fork of the official Git repository, as described in the <<development-contributing-chapter-index,contributing>> section.
Then they can fill in the URL of their clone instead, i.e. `+https://gitlab.eclipse.org/<username>/<cloned_repo_name>.git+`, with `<username>` replaced by their Eclipse Foundation account username, and `<cloned_repo_name>` replaced by the name of the cloned repistory, which defaults to `escet`.
** For _Eclipse Foundation account full name_ fill in your full name (first and last name) matching the full name in your Eclipse Foundation account.
This will be used as name for Git commits.
......@@ -102,8 +102,8 @@ In your new development environment, consider changing the following settings:
* For the _Package Explorer_ <<use-terminology-view,view>>:
** Enable the _Link with Editor_ setting, using the image:{developer-imgsdir}/link-with-editor.png[] icon.
** Enable the _Link with Editor_ setting, using the image:{development-imgsdir}/link-with-editor.png[] icon.
** Enable showing resources (files/folders) with names starting with a period.
Open the _View Menu_ (image:{developer-imgsdir}/view-menu.png[]) and choose menu:Filters...[].
Open the _View Menu_ (image:{development-imgsdir}/view-menu.png[]) and choose menu:Filters...[].
Uncheck the `+.* resources+` option and click btn:[OK].
......@@ -14,10 +14,10 @@ include::_part_attributes.asciidoc[]
indexterm:[development, process]
[[developer-development-process-chapter-index]]
[[development-development-process-chapter-index]]
== Development process
NOTE: If you want to contribute to the Eclipse ESCET project, please refer to the specific <<developer-contributing-chapter-index,contributing>> information.
NOTE: If you want to contribute to the Eclipse ESCET project, please refer to the specific <<development-contributing-chapter-index,contributing>> information.
Most of the information on this page will however also be applicable to and relevant for contributors, but not all of it.
The Eclipse ESCET project primarily uses GitLab for its development:
......@@ -28,14 +28,14 @@ The Eclipse ESCET project primarily uses GitLab for its development:
=== Discussion
It is often a good idea to first discuss new ideas and features with the rest of the project developers, i.e. the project committers and the project community.
Discussions can take place on the project's <<developer-chapter-index,'dev' list>>, especially for radical new ideas and new features that have not been discussed before.
Discussions can take place on the project's <<development-chapter-index,'dev' list>>, especially for radical new ideas and new features that have not been discussed before.
indexterm:[issue]
=== Issue tracking
If the project committers and the community agree that it is a good idea to have the new feature, an issue should be created in the <<developer-issue-tracking-chapter-index,issue tracker>>.
If the project committers and the community agree that it is a good idea to have the new feature, an issue should be created in the <<development-issue-tracking-chapter-index,issue tracker>>.
For improvements where extensive discussion is not expected, as well as for obvious bugs, an issue can be created directly, without first discussing it on the 'dev' list.
The discussion can also continue in the issue itself, once the issue is created.
......@@ -63,7 +63,7 @@ Removal of deprecated and obsolete functionality, code, documentation, etc is al
** Add all relevant component labels (e.g. 'Chi' and 'CIF' labels).
Typically at least one such label should be present, but it is also possible to add multiple labels if the issue involves multiple components.
The components correspond to the directories in the root of our <<developer-git-repo-chapter-index,Git repository>>.
The components correspond to the directories in the root of our <<development-git-repo-chapter-index,Git repository>>.
** The Eclipse ESCET project committers can add the 'Help Wanted' label to an issue to indicate that they don't have the time to work on the issue, and that help from the community is wanted.
......@@ -105,7 +105,7 @@ A contributor can ask the project committers to be unassigned.
* Don't unassign yourself after finishing the issue.
It is enough to close the issue.
The issue may also be closed automatically when an associated <<developer-development-process-merge-requests,merge request>> is merged.
The issue may also be closed automatically when an associated <<development-development-process-merge-requests,merge request>> is merged.
indexterm:[branch]
......@@ -153,7 +153,7 @@ Adapt the _Branch name_ and _Source_ as needed.
Typically the defaults suffice.
Click the _Create branch_ button to create the branch.
+
For contributors, see the <<developer-contributing-chapter-index,contributing>> section for the recommended approach.
For contributors, see the <<development-contributing-chapter-index,contributing>> section for the recommended approach.
* We prefer not to create a draft merge request with the creation of the branch, as then commits in the branch lead to commits on the merge requests, which lead to notification emails.
Instead, work in the branch until it is ready for review, and then create a merge request for it.
......@@ -196,12 +196,12 @@ Merge commits are exempt from this rule.
* All commits must adhere to the requirements as defined by the Eclipse Foundation.
See link:https://www.eclipse.org/projects/handbook/#resources-commit[Git Commit Records] in the Eclipse Foundation Project Handbook.
If you are not an Eclipse ESCET project committer, with write access to our Git repository, see the information on <<developer-contributing-chapter-index,contributing>> to the Eclipse ESCET project.
If you are not an Eclipse ESCET project committer, with write access to our Git repository, see the information on <<development-contributing-chapter-index,contributing>> to the Eclipse ESCET project.
indexterm:[merge request]
[[developer-development-process-merge-requests]]
[[development-development-process-merge-requests]]
=== Merge requests
Once the work on an issue is done and pushed to a branch, it must be reviewed before it is merged back.
......@@ -231,4 +231,4 @@ Include multiple of them if appropriate.
* If the branch fully addressed the associated issue or issues, it/they should be closed.
If you are not an Eclipse ESCET project committer, with write access to our Git repository, see the information on <<developer-contributing-chapter-index,contributing>> to the Eclipse ESCET project.
If you are not an Eclipse ESCET project committer, with write access to our Git repository, see the information on <<development-contributing-chapter-index,contributing>> to the Eclipse ESCET project.
......@@ -14,7 +14,7 @@ include::_part_attributes.asciidoc[]
indexterm:[Git, repository]
[[developer-git-repo-chapter-index]]
[[development-git-repo-chapter-index]]
== Git repository
The Eclipse ESCET project maintains the following source code repositories:
......@@ -31,11 +31,11 @@ indexterm:[Java]
The software is written in the https://www.oracle.com/java/[Java] programming language, as a collection of https://www.eclipse.org/pde/[Eclipse plugins], and using the https://www.eclipse.org/modeling/emf/[Eclipse Modeling Framework] (EMF).
For ease of programming, the https://eclipse.org[Eclipse IDE] is recommended.
See also the section on <<developer-dev-env-setup-chapter-index, setting up a development environment>>.
See also the section on <<development-dev-env-setup-chapter-index, setting up a development environment>>.
To contribute code (e.g. patches), documentation, or anything else, see the <<developer-contributing-chapter-index,contributing>> section.
To contribute code (e.g. patches), documentation, or anything else, see the <<development-contributing-chapter-index,contributing>> section.
The way we work with our Git repository is explained as part of our <<developer-development-process-chapter-index,development process>>.
The way we work with our Git repository is explained as part of our <<development-development-process-chapter-index,development process>>.
=== Repository structure
......
......@@ -12,7 +12,7 @@
include::_part_attributes.asciidoc[]
[[developer-chapter-index]]
[[development-chapter-index]]
== Eclipse ESCET development
Thanks for your interest in Eclipse Supervisory Control Engineering Toolkit (Eclipse ESCET) project.
......@@ -32,13 +32,13 @@ For other means to interact with the Eclipse ESCET community and its developers,
Further topics:
* <<developer-development-process-chapter-index>>
* <<developer-contributing-chapter-index>>
* <<developer-issue-tracking-chapter-index>>
* <<developer-dev-env-setup-chapter-index>>
* <<developer-git-repo-chapter-index>>
* <<developer-coding-standards-chapter-index>>
* <<developer-building-and-testing-chapter-index>>
* <<developer-release-process-chapter-index>>
* <<developer-third-party-tools-chapter-index>>
* <<developer-upgrade-instructions-chapter-index>>
* <<development-development-process-chapter-index>>
* <<development-contributing-chapter-index>>
* <<development-issue-tracking-chapter-index>>
* <<development-dev-env-setup-chapter-index>>
* <<development-git-repo-chapter-index>>
* <<development-coding-standards-chapter-index>>
* <<development-building-and-testing-chapter-index>>
* <<development-release-process-chapter-index>>
* <<development-third-party-tools-chapter-index>>
* <<development-upgrade-instructions-chapter-index>>
......@@ -16,7 +16,7 @@ indexterm:[issues]
indexterm:[issue, create]
indexterm:[GitLab]
[[developer-issue-tracking-chapter-index]]
[[development-issue-tracking-chapter-index]]
== Issue tracking
The Eclipse ESCET project uses GitLab to track ongoing development and issues:
......@@ -27,6 +27,6 @@ The Eclipse ESCET project uses GitLab to track ongoing development and issues:
Be sure to search for existing issues before you create another one.
Remember that contributions are always welcome!
To contribute code (e.g. patches), documentation, or anything else, see the <<developer-contributing-chapter-index,contributing>> section.
To contribute code (e.g. patches), documentation, or anything else, see the <<development-contributing-chapter-index,contributing>> section.
To understand how we work with issues, see our <<developer-development-process-chapter-index, development process>>.
To understand how we work with issues, see our <<development-development-process-chapter-index, development process>>.
......@@ -12,20 +12,20 @@
include::_part_attributes.asciidoc[]
[[developer-release-process-chapter-index]]
[[development-release-process-chapter-index]]
== Release process
This page explains step by step the various processes involved from preparing for a release to actually releasing it.
The following topics are covered:
* <<developer-release-process-plan-next-version>>
* <<developer-release-process-prepare-git-repo-for-next-version>>
* <<developer-release-process-working-on-a-release>>
* <<developer-release-process-prepare-release>>
* <<developer-release-process-perform-release>>
* <<development-release-process-plan-next-version>>
* <<development-release-process-prepare-git-repo-for-next-version>>
* <<development-release-process-working-on-a-release>>
* <<development-release-process-prepare-release>>
* <<development-release-process-perform-release>>
[[developer-release-process-plan-next-version]]
[[development-release-process-plan-next-version]]
=== Planning for a next version
For a new version (not milestone or release candidate), follow these steps.
......@@ -72,7 +72,7 @@ Replace `N.N` by the actual release record version, `0.1`, `0.1.1` or `1.0`.
** Click _Create milestone_.
[[developer-release-process-prepare-git-repo-for-next-version]]
[[development-release-process-prepare-git-repo-for-next-version]]
=== Preparing Git repository for a next version
To prepare the Git repository for the next version (not a milestone or release candidate), follow these steps:
......@@ -139,19 +139,19 @@ Check for unintended changes.
* Search the entire Git repository (all projects) for the old version number and update anything that still requires updating.
* Test that the <<developer-building-and-testing-chapter-index,build works>>.
* Test that the <<development-building-and-testing-chapter-index,build works>>.
[[developer-release-process-working-on-a-release]]
[[development-release-process-working-on-a-release]]
=== Working on a release
The work for the next release (milestone, release candidate, or final release) is done in the `develop` branch.
See the <<developer-development-process-chapter-index,development process>> for more information.
See the <<development-development-process-chapter-index,development process>> for more information.
Note that for each version at least one milestone release and at least one release candidate are required before a final release.
[[developer-release-process-prepare-release]]
[[development-release-process-prepare-release]]
=== Preparing a release
Once the work on `develop` is done for a release (milestone, release candidate, or final release), follow these steps to prepare for the release:
......@@ -180,7 +180,7 @@ See e.g. https://www.eclipse.org/lists/escet-dev/msg00091.html (mail also sent t
** Ensure the release review is successful before performing the release.
[[developer-release-process-perform-release]]
[[development-release-process-perform-release]]
=== Performing a release
To perform a release (milestone, release candidate, or final release), i.e. actually release it, follow these steps:
......
......@@ -12,7 +12,7 @@
include::_part_attributes.asciidoc[]
[[developer-third-party-tools-chapter-index]]
[[development-third-party-tools-chapter-index]]
== Third party tools
As part of development for the Eclipse ESCET project, several third party tools are used.
......
......@@ -12,13 +12,13 @@
include::_part_attributes.asciidoc[]
[[developer-upgrade-instructions-chapter-index]]
[[development-upgrade-instructions-chapter-index]]
== Upgrade instructions
To upgrade to a new Eclipse Platform/IDE/SDK version:
* New development environment
** <<developer-dev-env-setup-chapter-index,Set up a new development environment>> for the new Eclipse IDE version.
** <<development-dev-env-setup-chapter-index,Set up a new development environment>> for the new Eclipse IDE version.
* Version updates
** Look up Orbit version for the new Eclipse Platform/IDE/SDK release, see https://download.eclipse.org/tools/orbit/downloads/.
......@@ -67,7 +67,7 @@ To upgrade to a new Eclipse Platform/IDE/SDK version:
** Ensure the Maven version in `misc/license-check-dependencies/Jenkinsfile` matches the embedded Maven version.
* Validation
** Run a <<developer-building-and-testing-chapter-index,Maven build>>.
** Run a <<development-building-and-testing-chapter-index,Maven build>>.
** Ensure no errors or warnings during Maven build.
* Dependency information
......@@ -79,7 +79,7 @@ To upgrade to a new Tycho version:
* Update version in `org.eclipse.escet.root/.mvn/extensions.xml`.
* Update version in `org.eclipse.escet.configuration/pom.xml`.
* Check Tycho release notes for changes and adapt as necessary.
* Run a <<developer-building-and-testing-chapter-index,Maven build>>.
* Run a <<development-building-and-testing-chapter-index,Maven build>>.
* Ensure no errors or warnings during Maven build.
To upgrade to a new Java version:
......@@ -100,7 +100,7 @@ To upgrade to a new Java version:
** Update the JustJ version in the product (`org.eclipse.escet.product/escet.product`).
** Update `dev-env-setup.asciidoc` to match new Java version.
** Force a rebuild in Eclipse (menu:Project[Clean...]) and check for any warnings/errors, addressing them if any.
** Run a <<developer-building-and-testing-chapter-index,Maven build>>.
** Run a <<development-building-and-testing-chapter-index,Maven build>>.
** Ensure no errors or warnings during Maven build.
** Run `misc/license-check-dependencies/license-check-dependencies.sh` and update `DEPENDENCIES.txt` according to the output.
** Run `misc/license-check-dependencies/license-check-dependencies.sh` to ensure `DEPENDENCIES.txt` is up-to-date.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment