-
Notifications
You must be signed in to change notification settings - Fork 132
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: streamline main readme for npm and update website versioning
- add clickable FDC3 logo at top of README that goes to fdc3.finos.org - simplify description of FDC3 and link to the four specifications that make up the standard, and use cases - add installation and usage sections to the README that concisely demonstrate how to use FDC3 - add a documentation section that explicitly links to the documentation website, without hardcoded version URLs - improve formatting of "Getting Involved" section to make it more readable - simplify the roadmap, removing things already achieved, and summarising to 5 steps - move the Contributing section to the end - website: remove previous workaround to "hard code" docusaurus urls to the latest version, meaning we can use unversioned links in the readme
- Loading branch information
Showing
12 changed files
with
147 additions
and
115 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,87 +1,128 @@ | ||
| [](https://github.com/finos/FDC3/actions?query=workflow%3Anpm-build) | ||
| [](https://github.com/finos/FDC3/actions?query=workflow%3Awebsite-build) | ||
| # <a href='http://fdc3.finos.org'><img src='./website/static/img/fdc3-logo-2019-color.png' height='150' alt='FDC3 Logo' aria-label='fdc3.finos.org' /></a> | ||
|
|
||
| [](https://github.com/finos/fdc3/releases/latest) | ||
| [](https://www.npmjs.com/package/@finos/fdc3) | ||
| [](https://finosfoundation.atlassian.net/wiki/display/FINOS/Released) | ||
| [](https://opensource.org/licenses/Apache-2.0 | ||
| ) | ||
| [](https://opensource.org/licenses/Apache-2.0) | ||
| [](https://stackoverflow.com/questions/tagged/fdc3) | ||
| [](https://github.com/finos/FDC3/actions?query=workflow%3Anpm-build) | ||
| [](https://github.com/finos/FDC3/actions?query=workflow%3Awebsite-build) | ||
|
|
||
| # FDC3 | ||
| FDC3 aims to provide open standards for the financial desktop. This includes standardized verbs to invoke actions between applications (called "intents"), a standardized data format, an OpenAPI app directory standard, and a set of standardized interoperability APIs. | ||
|
|
||
| The mission of the Financial Desktop Connectivity and Collaboration Consortium (FDC3) is to develop specific protocols and taxonomies to advance the ability of desktop applications in financial workflows to interoperate in a plug-and-play fashion and without prior, bi-lateral agreements. | ||
| The FDC3 standard currently consists of four specifications: | ||
|
|
||
| ## About this Repository | ||
| FDC3 is a standard. This repository houses the documentation and specifications for the ratified FDC3 standards. | ||
| 1. [API Specification](https://fdc3.finos.org/docs/api/spec) | ||
| 2. [Intents Specification](https://fdc3.finos.org/docs/intents/spec) | ||
| 3. [Context Data Specification](https://fdc3.finos.org/docs/context/spec) | ||
| 4. [App Directory Specification](https://fdc3.finos.org/docs/app-directory/spec) | ||
|
|
||
| ## Using the standard | ||
| Check out [the documentation website](https://fdc3.finos.org) for the different components of the standard, an overview of [common use cases](https://fdc3.finos.org/docs/1.1/use-cases/overview), developer [API docs](https://fdc3.finos.org/docs/1.1/api/overview) and [standard compliance information](https://fdc3.finos.org/docs/1.1/fdc3-compliance). | ||
| The specifications are informed by agreed [business use cases](https://fdc3.finos.org/docs/use-cases/overview), | ||
| and implemented and used by leading [financial industry participants](https://fdc3.finos.org/users). | ||
|
|
||
| Latest version of the standard is [1.1](https://fdc3.finos.org/docs/1.1/fdc3-intro). See [all available versions](https://fdc3.finos.org/versions). | ||
| ## Installation | ||
|
|
||
| ## Learn more and interact with the Community | ||
| To learn more and ask questions you subscribe to the [FDC3 General List](fdc3@finos.org) by emailing [fdc3+subscribe@finos.org](mailto:fdc3+subscribe@finos.org). Another great way to interact with the standard participants is to attend the quarterly [FDC3 General meeting](https://github.com/finos/FDC3/issues?q=label%3A%22General+Meeting%22): you should receive an invite by signing up to the general list or you can find the meeting in the [FINOS Project Meetings Calendar](https://calendar.google.com/calendar/embed?src=finos.org_fac8mo1rfc6ehscg0d80fi8jig%40group.calendar.google.com). | ||
| ``` | ||
| npm install @finos/fdc3 | ||
| ``` | ||
|
|
||
| ## Using the standard? Let us know! | ||
| If you an existing individual or corporate user of the FDC3 standard, we would love to hear from you: just email the [FDC3 General List](fdc3@finos.org) with details about how you are using the standard. If you'd like to be listed as a standard user, you can directly [send a pull request to update our website](./website/data/users.json) or, if listing your logo publicly requires legal evaluation, you can reach out privately to the [FDC3 Product Management Committee](fdc3-private@finos.org). | ||
| For more details, please see the [the Installation docs page](https://fdc3.finos.org/docs/installation). | ||
|
|
||
| ## Participate in the standard process | ||
| The [FDC3 Standard Working Group](https://github.com/finos/FDC3/issues?q=label%3A%22Standard+WG+Meeting%22) meets monthly: you are welcome to join by subscribing to the [FINOS Project Meetings Calendar](https://calendar.google.com/calendar/embed?src=finos.org_fac8mo1rfc6ehscg0d80fi8jig%40group.calendar.google.com). If you'd like to formally enroll as a voting standard participant process (as described in [our standards governance](https://github.com/finos/community/tree/master/governance/Standards-Projects#joining-a-standards-project-grace-period-for-new-participants)) please email [fdc3-participants+subscribe@finos.org](mailto:fdc3-participants+subscribe@finos.org?subject=Please%20enroll%20me%20as%20FDC3%20standard%20participant&cc=fdc3-pmc%40finos.org&body=HI%2C%20my%20name%20is%20%3CFirstName%20LastName%3E%20and%20I%27d%20like%20to%20formally%20participate%20to%20the%20FDC3%20standard%20process.%20I%20plan%20to%20contribute%20as%20%3Cindividual%7Con%20behalf%20of%20organizationName%3E%20and%20I%20have%20reviewed%20the%20policies%20described%20at%20https%3A%2F%2Fgithub.com%2Ffinos%2Fcommunity%2Ftree%2Fmaster%2Fgovernance%2FStandards-Projects%20.%20Thank%20you!) making your intent to participate in the standard process explicit. Please note that standard participants are bound to the provisions in the [FINOS IP Policy](https://github.com/finos/community/blob/master/governance/IP-Policy.pdf) as described in the [FINOS standards governance](https://github.com/finos/community/tree/master/governance/Standards-Projects). | ||
| ## Usage | ||
|
|
||
| ## Contributing code to this repository | ||
| If you'd like to contribute code to this repository: | ||
|
|
||
| 1. Fork it (<https://github.com/finos/FDC3/fork>) | ||
| 2. Create your feature branch (`git checkout -b feature/fooBar`) | ||
| 3. Commit your changes (`git commit -am 'Add some fooBar'`) | ||
| 4. Push to the branch (`git push origin feature/fooBar`) | ||
| 5. Create a new Pull Request | ||
| ```ts | ||
| // declare FDC3-compliant data | ||
| const instrument = { | ||
| type: 'fdc3.instrument', | ||
| id: { | ||
| ticker: 'AAPL', | ||
| ISIN: 'US0378331005', | ||
| FIGI : 'BBG000B9XRY4' | ||
| } | ||
| } | ||
|
|
||
| // invoke an action in another application | ||
| const result = await fdc3.raiseIntent('ViewAnalysis', instrument) | ||
|
|
||
| // join the red channel and broadcast data to subscribers | ||
| await fdc3.joinChannel('red') | ||
| fdc3.broadcast(instrument) | ||
|
|
||
| // set up a listener for incoming data | ||
| const listener = fdc3.addContextListener('fdc3.contact', contact => { }) | ||
| ``` | ||
|
|
||
| ## Documentation | ||
|
|
||
| The FDC3 docs are located at **https://fdc3.finos.org**: | ||
|
|
||
| - [Introduction](http://fdc3.finos.org/docs/fdc3-intro) | ||
| - [FDC3 Charter](http://fdc3.finos.org/docs/fdc3-charter) | ||
| - [FDC3 Compliance](http://fdc3.finos.org/docs/fdc3-compliance) | ||
| - [API Reference](https://fdc3.finos.org/docs/api/ref/DesktopAgent) | ||
|
|
||
| ## Getting Involved | ||
|
|
||
| The team will review the PR and decide about merging. | ||
| - ### **Learn more and interact with the community** | ||
|
|
||
| Note that you will require a contributor agreement (individual or corporate) before your code can be merge, so please review [FINOS Contribution requirements](.github/CONTRIBUTING.md). | ||
| To learn more and ask questions you can subscribe to the [FDC3 General List] by emailing [fdc3+subscribe@finos.org]. | ||
|
|
||
| Another great way to interact with the standard participants is to attend the quarterly [FDC3 General Meeting]: you will receive an invite by signing up to the general list, or you can find the meeting in the [FINOS Project Meetings Calendar]. | ||
|
|
||
| _NOTE:_ Commits and pull requests to FINOS repositories will only be accepted from those contributors with an active, executed Individual Contributor License Agreement (ICLA) with FINOS OR who are covered under an existing and active Corporate Contribution License Agreement (CCLA) executed with FINOS. Commits from individuals not covered under an ICLA or CCLA will be flagged and blocked by the FINOS Cla-bot tool. Please note that some CCLAs require individuals/employees to be explicitly named on the CCLA. | ||
| - ### **Let us know if you are using the standard!** | ||
|
|
||
| *Need an ICLA? Unsure if you are covered under an existing CCLA? Email [help@finos.org](mailto:help@finos.org)* | ||
| If you an existing individual or corporate user of the FDC3 standard, we would love to hear from you: just email the [FDC3 General List] with details about how you are using the standard. | ||
|
|
||
| If you'd like to be listed as a standard user, you can directly [send a pull request to update the website] or, if listing your logo publicly requires legal evaluation, you can reach out privately to the [FDC3 Product Management Committee]. | ||
|
|
||
| - ### **Participate in the standard process** | ||
|
|
||
| The [FDC3 Standard Working Group] meets monthly: you are welcome to join by subscribing to the [FINOS Project Meetings Calendar]. | ||
|
|
||
| If you would like to formally enroll as a voting Standard participant (as described in [our standards governance]), please email [fdc3-participants+subscribe@finos.org], making your intent to participate in the standard process explicit. Please note that standard participants are bound to the provisions in the [FINOS IP Policy] as described in the [FINOS standards governance]. | ||
|
|
||
| [FDC3 General List]: fdc3@finos.org | ||
| [FDC3 Product Management Committee]: fdc3-private@finos.org | ||
| [FDC3 General Meeting]: https://github.com/finos/FDC3/issues?q=label%3A%22General+Meeting%22 | ||
| [FDC3 Standard Working Group]: https://github.com/finos/FDC3/issues?q=label%3A%22Standard+WG+Meeting%22 | ||
|
|
||
| [send a pull request to update the website]: https://github.com/finos/FDC3/edit/master/website/data/users.json | ||
|
|
||
| [FINOS Project Meetings Calendar]: https://calendar.google.com/calendar/embed?src=finos.org_fac8mo1rfc6ehscg0d80fi8jig%40group.calendar.google.com | ||
| [our standards governance]: https://github.com/finos/community/tree/master/governance/Standards-Projects#joining-a-standards-project-grace-period-for-new-participants | ||
|
|
||
| [FINOS IP Policy]: https://github.com/finos/community/blob/master/governance/IP-Policy.pdf | ||
| [FINOS standards governance]: https://github.com/finos/community/tree/master/governance/Standards-Projects | ||
|
|
||
| [fdc3+subscribe@finos.org]: mailto:fdc3+subscribe@finos.org | ||
| [fdc3-participants+subscribe@finos.org]: mailto:fdc3-participants+subscribe@finos.org?subject=Please%20enroll%20me%20as%20FDC3%20standard%20participant&cc=fdc3-pmc%40finos.org&body=HI%2C%20my%20name%20is%20%3CFirstName%20LastName%3E%20and%20I%27d%20like%20to%20formally%20participate%20to%20the%20FDC3%20standard%20process.%20I%20plan%20to%20contribute%20as%20%3Cindividual%7Con%20behalf%20of%20organizationName%3E%20and%20I%20have%20reviewed%20the%20policies%20described%20at%20https%3A%2F%2Fgithub.com%2Ffinos%2Fcommunity%2Ftree%2Fmaster%2Fgovernance%2FStandards-Projects%20.%20Thank%20you! | ||
|
|
||
| ## Roadmap | ||
| With Productization on track to land at end of Q1, the expectation is that Q2 will be focused on implementations and feedback from those implementations driving further standards. | ||
| ### Target Items for Q2 | ||
| #### API | ||
| * Expand the broadcast API or introduce a new channels API to support the context setting use case. | ||
| * Publish npm package with FDC3 API definitions. | ||
|
|
||
| #### App Directory | ||
| * Search capabilities, surfacing other content | ||
| * Manifest format detail (describing the content) | ||
| * Eventing | ||
|
|
||
| #### Context Data | ||
| * Pivot to JSON schema for representing type definitions. We have found that TypeScript is too implementation-specific and too restrictive in practice. | ||
| * Use https://quicktype.io/ to generate type definitions from JSON schema for multi-language support. | ||
| * Formalise current example types into official FDC3 types for contact, organisation, instrument etc in conjunction with/based on the Financial Objects program work. | ||
|
|
||
| #### Intents | ||
| * Add detailed documentation to each intent - linking to use cases | ||
| * Align closer with Context Data WG | ||
| * Evaluate real use cases, given that we have input from early adapters | ||
| * Extend with new intents, based on above + accepted use cases | ||
|
|
||
| #### Use Cases | ||
| * Continue to process new and existing FDC3 Use Cases | ||
| * Assess extending the use cases working group to additional FINOS programs | ||
|
|
||
| ### Backlog Beyond Q2 | ||
| * Define the next set of FDC3 Context Data types in conjunction with/based on Financial Objects working group work. | ||
| * Work with Financial Objects and other FINOS programs to reach consensus on how to make standardized taxonomies available for consumption, both for viewing/editing and programmatically e.g. for validation. | ||
| * Create comprehensive examples of use cases that show how to use the various FDC3 standards together to enable interoperability. | ||
| * App Directory Identity and authentication | ||
|
|
||
| 1. Publish an NPM package to ease adoption and implementation of FDC3 APIs. | ||
| 2. Work towards version 1.2 of the FDC3 Standard, with expanded API capabilities. | ||
| 3. Establish a process to accelerate community-contributed context data definitions. | ||
| 4. Improve the App Directory specification. | ||
| 5. Continue building out business use cases to inform future versions of the FDC3 Standard. | ||
|
|
||
| ## Contributing | ||
|
|
||
| 1. Fork it (<https://github.com/finos/FDC3/fork>) | ||
| 2. Create your feature branch (`git checkout -b feature/fooBar`) | ||
| 3. Read our [contribution guidelines](CONTRIBUTING.md) and [Community Code of Conduct](https://www.finos.org/code-of-conduct) | ||
| 4. Commit your changes (`git commit -am 'Add some fooBar'`) | ||
| 5. Push to the branch (`git push origin feature/fooBar`) | ||
| 6. Create a new Pull Request | ||
|
|
||
| _NOTE:_ Commits and pull requests to FINOS repositories will only be accepted from those contributors with an active, executed Individual Contributor License Agreement (ICLA) with FINOS OR who are covered under an existing and active Corporate Contribution License Agreement (CCLA) executed with FINOS. Commits from individuals not covered under an ICLA or CCLA will be flagged and blocked by the FINOS Clabot tool. Please note that some CCLAs require individuals/employees to be explicitly named on the CCLA. | ||
|
|
||
| *Need an ICLA? Unsure if you are covered under an existing CCLA? Email [help@finos.org](mailto:help@finos.org).* | ||
|
|
||
| ## License | ||
|
|
||
| Copyright 2017 FDC3 | ||
|
|
||
| Distributed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0). | ||
|
|
||
| SPDX-License-Identifier: [Apache-2.0](https://spdx.org/licenses/Apache-2.0) | ||
| SPDX-License-Identifier: [Apache-2.0](https://spdx.org/licenses/Apache-2.0) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.