Skip to content

Commit

Permalink
solving #2 issue: add PR template and contributing.md to answer reque…
Browse files Browse the repository at this point in the history
…sts for PR #4
  • Loading branch information
kevin-delmas committed Nov 17, 2023
1 parent a939edd commit f578dcd
Show file tree
Hide file tree
Showing 3 changed files with 147 additions and 81 deletions.
93 changes: 37 additions & 56 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -1,71 +1,52 @@
## Description

<!--
Please do not leave this blank
This PR [adds/removes/fixes/replaces] the [feature/bug/etc].
-->

## What type of PR is this? (check all applicable)

- [ ] 🍕 Feature
- [ ] 🐛 Bug Fix
- [ ] 📝 Documentation Update
- [ ] 🎨 Style
- [ ] 🧑‍💻 Code Refactor
- [ ] 🔥 Performance Improvements
- [ ] ✅ Test
- [ ] 🤖 Build
- [ ] 🔁 CI
- [ ] 📦 Chore (Release)
- [ ] ⏩ Revert
Please indicate whether this pull request [adds/removes/fixes/replaces] the [feature/bug/etc].

## What type of pull request is this? (check all applicable)

- [ ] Feature
- [ ] Bug Fix
- [ ] Documentation Update
- [ ] Style
- [ ] Code Refactor
- [ ] Performance Improvements
- [ ] Test
- [ ] Build
- [ ] CI
- [ ] Chore (Release)
- [ ] Revert

## Related Tickets & Documents
<!--
Please use this format link issue numbers: Fixes #123
https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword
-->

## Mobile & Desktop Screenshots/Recordings

<!-- Visual changes require screenshots -->

If possible ensure that you have provided in your commit message the issue id (available [here](https://github.com/onera/pml-analyzer/issues)) this pull request fixes,
for instance to refer to issue #42 you can do:
```shell
git commit -m "solving issue #42 with ..."
```
Check [here](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) for more information

## Added tests?

- [ ] 👍 yes
- [ ] 🙅 no, because they aren't needed
- [ ] 🙋 no, because I need help
- [ ] yes
- [ ] no, because they aren't needed
- [ ] no, because I need help

## Added to documentation?

- [ ] 📜 README.md
- [ ] 📓 docs.opensauced.pizza
- [ ] 🍕 dev.to/opensauced
- [ ] 📕 storybook
- [ ] 🙅 no documentation needed

## [optional] Are there any post-deployment tasks we need to perform?



## [optional] What gif best describes this PR or how it makes you feel?
- [ ] README.md
- [ ] doc
- [ ] no documentation needed

## Do we need to update pml analyzer version?

- [ ] no
- [ ] the pull request is only a bug fix, need a bug fix version update
- [ ] the pull request add new features and ensures retro-compatibility, need a feature addition version update
- [ ] the pull request is not ensuring retro-capatibility, need a major version update
- [ ] not sure, I need help

<!-- note: PRs with deleted sections will be marked invalid -->
## Is this new version should be released as soon as possible?

<!--
For Work In Progress Pull Requests, please use the Draft PR feature,
see https://github.blog/2019-02-14-introducing-draft-pull-requests/ for further details.
For a timely review/response, please avoid force-pushing additional
commits if your PR already received reviews or comments.
Before submitting a Pull Request, please ensure you've done the following:
- 📖 Read the Open Sauced Contributing Guide: https://github.com/open-sauced/.github/blob/main/CONTRIBUTING.md.
- 📖 Read the Open Sauced Code of Conduct: https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md.
- 👷‍♀️ Create small PRs. In most cases, this will be possible.
- ✅ Provide tests for your changes.
- 📝 Use descriptive commit messages.
- 📗 Update any related documentation and include any relevant screenshots.
-->
- [ ] yes
- [ ] no
- [ ] not sure, I need help
45 changes: 20 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ The only dependencies of the PML analyzer are:

### build.sbt

To get pml analyzer simply add the following line to your build.sbt file:
To get the version X.Y.Z of pml analyzer simply add the following line to your build.sbt file:
```scala
libraryDependencies += "io.github.onera" % "pml_analyzer" % "1.0.0"
libraryDependencies += "io.github.onera" % "pml_analyzer" % "X.Y.Z"
```

## Installing dependencies
Expand Down Expand Up @@ -45,6 +45,13 @@ java -jar -Djava.library.path=yourPath sbt-launch.jar
# to run a JAR
java -jar -Djava.library.path=yourPath youJar.jar
```
### Cecilia

It is possible to export PML models as [CeciliaOCAS](https://satodev.com/nos-produits/cecilia-workshop/) or [OpenAltarica](https://www.openaltarica.fr/docs-downloads/) models and perform automatic analyses or simulation out of these models.

### IDP

It is possible to use [IDP](https://dtai.cs.kuleuven.be/software/idp/try) as an alternative to MONOSAT to perform the interference analyses out of your PML model.

## Using the PML analyzer

Expand All @@ -60,14 +67,10 @@ or unlinking entities) are provided in the ``pml.operators`` package.
Exporters to [yuml](https://yuml.me/diagram) and [graphviz](http://www.graphviz.org/) are provided in the ``pml.exporters`` package.

The compilation of a PML model can be easily perform with [SBT](https://www.scala-sbt.org/)
+ First launch sbt in the project repository (this operation may take some time)
```sbtshell
sbt
Simply run the following command in the project repository (this operation may take some time)
```shell
sbt runMain pathToYourModel
```
+ Once sbt is ready to receive command launch the compilation and execution of your PML model
```sbtshell
runMain pathToYourModel
```

### Editing a PML Model

Expand All @@ -84,8 +87,8 @@ your modeling activity.

To edit PML model with Intellij please follow the installation steps given by [JetBrain](https://www.jetbrains.com).
The installation can be made for any platform and does not require any administrator privilege.
Once the Intellij is installed please download the Scala and SBT Executor plugins.

Once the Intellij IDE is installed please download the Scala and SBT Executor plugins.
More information are available on the [Intellij Scala 3 support guide](https://dotty.epfl.ch/3.0.0/docs/usage/ide-support.html)
#### Creating a project with Intellij

The build specifications and project structure are provided with the PML source code.
Expand All @@ -110,7 +113,7 @@ dynamic library of monosat by editing your run configuration and adding to VM op

#### Argumentation patterns

The justification patterns considered for the CAST32-A are provided in the ``views.patterns`` package.
The justification patterns considered for the AMC20-193 (former CAST32-A) are provided in the ``views.patterns`` package.
These patterns can be used as a starting point to start your argumentation activity.

To compile and run the PHYLOG patterns example please enter the following commands:
Expand All @@ -125,16 +128,16 @@ your modeling activity.

To compile and run the Keystone example please enter the following commands:
```sbtshell
sbt runMain pml.examples.keystone.SimpleKeystoneExport
sbt runMain pml.examples.simpleKeystone.SimpleKeystoneExport
```

#### Analysis
For each view (interference, patterns and dependability) examples are provided in the dedicated ``views.X.examples``.
These benchmarks can be used as a starting point to
your analysis activity. For instance, we can carry out the interference analysis of the Keystone platform with
```sbtshell
# example of a PML model where an IDP interference model is generated
sbt runMain views.interference.examples.SimpleKeystoneInterferenceGeneration
# example of a PML model where a MONOSAT based interference identification is performed
sbt runMain views.interference.examples.simpleKeystone.SimpleKeystoneInterferenceGeneration
```

If the tool is running on a Unix System you can use the Makefile to compile the DOT and LaTeX generated file:
Expand All @@ -149,7 +152,7 @@ make patterns
make png
```

### Packaging
### Package your model

All projects can be packaged into a single FATJAR containing all non-native dependencies.
The available projects can be obtained by running:
Expand All @@ -166,12 +169,4 @@ The resulting FATJAR will be produced in projectName/target/scala3.2.2
If your system contains a docker engine, you can build a docker image by running the following command:
```sbtshell
sbt docker
```

### External tools

The PML modeling does not rely on any external dependency. Nevertheless, it is possible
to connect some backend analysis tools to directly perform analyses out of your PML model:
* for interference analysis: [IDP](https://dtai.cs.kuleuven.be/software/idp/try) or [Monosat](https://github.com/sambayless/monosat)
* for the safety analysis: [CeciliaOCAS]() or [OpenAltarica](https://www.openaltarica.fr/docs-downloads/)

```
90 changes: 90 additions & 0 deletions contributing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Contributing

When contributing to this repository, please first discuss the change you wish to make via issue,
email, or any other method with the owners of this repository before making a change.

## Pull Request Process

1. Fork, then clone the repo:
```shell
git clone [email protected]:your-username/pml-analyzer.git
```
2. See README.md to set up your machine.
3. Make sure the tests pass:
```shell
sbt test
```
4. Make your change and please follow the [Scala 3 coding and documentation style guide](https://docs.scala-lang.org/style/).
5. Add tests for your change. Make the tests pass:
```shell
sbt test
```
6. Update the README.md with details of changes to the API or the analysis process.
7. Increase the version numbers in any examples files, the README.md and the build.sbt to the new version that this
Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
```scala
//Change version in build.sbt
version := "X.Y.Z"
```
8. You may merge the Pull Request in once you have the sign-off of two other developers, or if you
do not have permission to do that, you may request the second reviewer to merge it for you.

## Code of Conduct

In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.

### Our Standards

Examples of behavior that contributes to creating a positive environment
include:

* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting

### Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.

### Scope

This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.

### Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at [http://contributor-covenant.org/version/1/4][version]

[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/

0 comments on commit f578dcd

Please sign in to comment.