Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove if-plugins from readme docs #840

Merged
merged 4 commits into from
Jun 18, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 10 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,6 @@
> [!IMPORTANT]
> Incubation Project: This project is an incubation project being run inside the Green Software Foundation; as such, we DON’T recommend using it in any critical use case. Incubation projects are experimental, offer no support guarantee, have minimal governance and process, and may be retired at any moment. This project may one day Graduate, in which case this disclaimer will be removed.

**Note** We have recently (March 2024) refactored the IF codebase and introduced some changes affecting both users and developers. You can read our migration guide [HERE](./Refactor-migration-guide.md) to help you update to the latest version!

[Impact Framework](https://greensoftwarefoundation.atlassian.net/wiki/spaces/~612dd45e45cd76006a84071a/pages/17072136/Opensource+Impact+Engine+Framework) (IF) is an [Incubation](https://oc.greensoftware.foundation/project-lifecycle.html#incubation) project from the [Open Source Working Group](https://greensoftwarefoundation.atlassian.net/wiki/spaces/~612dd45e45cd76006a84071a/pages/852049/Open+Source+Working+Group) in the [Green Software Foundation](https://greensoftware.foundation/).

**Our documentation is online at [if.greensoftware.foundation](https://if.greensoftware.foundation/)**

**IF** is a framework to **M**odel, **M**easure, si**M**ulate and **M**onitor the environmental impacts of software
Expand All @@ -23,54 +19,39 @@ Read the [specification and design docs](https://if.greensoftware.foundation) to

## Get started

The first thing to understand is that IF is a framework for running plugins. This means that in order to do some calculations, you need to load some plugins from some external resource. We provide a [standard library of plugins](https://github.com/Green-Software-Foundation/if-plugins) and a repository of [community plugins](https://github.com/Green-Software-Foundation/if-unofficial-plugins) to get you started.
IF is a framework for running pipelines of plugins that operate on a set of observations. This is all configured using a manifest file. We provide a standard library of plugins that come bundled with IF - we refer to these as `builtins`. We also have an [Explorer](https://explorer.if.greensoftware.foundation) where anyone can list third party plugins you can install.

Start by installing framework itself:
Start by installing the latest version of IF:

```sh
npm install -g "@grnsft/if"
```

Then installing some plugins:

```sh
npm install -g "@grnsft/if-plugins"
```

Then create a `manifest` file that describes your application (see our docs for a detailed explanation).

Then, run `if` using the following command:

```sh
if-run --manifest <path-to-your-manifest-file>
if-run --manifest <path-to-your-manifest-file> --stdout
## or you can use aliases
if-run -m <path-to-your-manifest-file>
if-run -m <path-to-your-manifest-file> -s

```

Note that above command will not print the final output. In order to print the final output to the console, run `if` using the optional stdout argument:
Note that above command will print your outputs to the console. You can also provide the `--output` command to save your outputs to a yaml file:

```sh
if-run --manifest <path-to-your-manifest-file> --stdout
## or using aliases
if-run -m <path-to-your-manifest-file> -s
if-run -m <path-to-your-manifest> -o <savepath>
```

You can also add a savepath for your output yaml in order to have the output stored in a file. Note that you also have to add configuration to your manifest to enable this, as follows:
Note that you also have to add configuration to your manifest to enable this, as follows:

```yaml
initialize:
output:
- yaml
```

On the command line:

```sh
if-run --manifest <path-to-your-manifest-file> --output <your-savepath>
## or using aliases
if-run -m <path-to-your-manifest-file> -o <your-savepath>
```

The `if-run` CLI tool will configure and run the plugins defined in your input `yaml` (`manifest`) and return the results as an output `yaml` (`output`).

Use the `debug` command if you want to diagnose and fix errors in your plugin:
Expand All @@ -91,6 +72,7 @@ if-run -h

Please read our documentation at [if.greensoftware.foundation](https://if.greensoftware.foundation/)


## Video walk-through

Watch this video to learn how to create and run a `manifest`.
Expand All @@ -107,11 +89,10 @@ We have a public mailing list at [[email protected]](https:/

To contribute to IF, please fork this repository and raise a pull request from your fork.

You can check our issue board for issues tagged `help-wanted`. These are issues that are not currently, actively being worked on by the core team but are well-scoped enough for someone to pick up. We recommend commenting on the issue to start a chat with the core team, then start working on the issue when you have been assigned to it. This process helps to ensure your work is aligned with our roadmap and makes it much more likely that your changes will get merged compared to unsolicited PRs.
You can check our issue board for issues. We mark some issues `core-only` if they are somehow sensitive and we want one of our core developers to handle it. Any other issues are open for the community to work on. We recommend commenting on the issue to start a chat with the core team, then start working on the issue when you have been assigned to it. This process helps to ensure your work is aligned with our roadmap and makes it much more likely that your changes will get merged compared to unsolicited PRs.

Please read the full contribution guidelines at [if.greensoftware.foundation](https://if.greensoftware.foundation/Contributing)

The same guidelines also apply to `if-docs`, `if-plugins` and `if-unofficial-plugins`.

## Bug reports

Expand Down