Update docs to deprecate V1 and add basic V2 job by samsondav · Pull Request #229 · smartcontractkit/documentation

samsondav · 2021-07-16T12:58:17Z

No description provided.

netlify · 2021-07-16T13:02:40Z

✔️ Deploy Preview for dreamy-villani-0e9e5c ready!

🔨 Explore the source changes: 25dde27

🔍 Inspect the deploy log: https://app.netlify.com/sites/dreamy-villani-0e9e5c/deploys/6112e99297b0290007a0bf1a

😎 Browse the preview: https://deploy-preview-229--dreamy-villani-0e9e5c.netlify.app

alexroan

Very informative docs, nice work!

We could structure the pages a little better to reduce the cognitive load in finding what readers need. Some context, maybe an intro page explaining the two formats and what changed, will go a long way to improving the information architecture.

alexroan · 2021-07-19T10:40:51Z

-          { url: '/docs/initiators/', title: 'Initiators' },
+          { url: '/docs/jobs/', title: 'Jobs' },
+          { url: '/docs/tasks/', title: 'Tasks' },
+          { url: '/docs/job-specifications/', title: 'Job Specifications [DEPRECATED]' },


I think there's a better way we can structure the deprecated pages. Maybe version 1 and 2 parent pages, with 2 being the default?

What is a parent page?

Here's an example of one: https://docs.chain.link/docs/reference-contracts/

Take a look at the menu item, it acts as a parent to sub-pages.

alexroan · 2021-07-19T10:50:09Z

+medianize_data -> submit_to_ea
+```
+
+![DAG Example](./dag_example.png)


This image isn't showing on my local or the generated preview. I believe assets like this are stored in _src/images/.

PatrickAlphaC

This looks great. As we learn more we will probably update something here. We will probably want to update our blogs on this as well with a note about the change.

ie: https://blog.chain.link/build-and-use-external-adapters/
https://www.youtube.com/watch?v=65NhO5xxSZc
https://www.youtube.com/watch?v=4i75Dqbhjvw

Please ping me to change these when this change goes live

connorwstein · 2021-07-21T14:08:03Z

+```
+
+- `contractAddress`: the address of the FluxAggregator contract that manages the feed.
+- `precision`: the number of decimal places to be associated the integer value submitted on-chain.


ditto - remove

connorwstein · 2021-07-21T14:09:29Z

+confirmations = 6
+publicKey = "0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F8179800"
+observationSource="""
+getrandomvalue [type=vrf];


this might change quite soon, I'd hold off on merging this until we have tested it using ethtx tasks

connorwstein · 2021-07-21T14:15:38Z

+### VRF
+
+```toml
+uuid = "123e4567-e89b-12d3-a456-426655440000"


this is now called externalJobID and is a universal parameter across all V2 specs. Probably deserves its own little blurb something like

The externalJobID is a optionally user-specified way to deterministically provide an ID of a job. Say for example you want to run the same directrequest job on two different chainlink nodes which have different bridge names. Although the actually spec contents differ slightly, you can use the same externalJobID on both, specify that in your on-chain requests and both nodes will pick it up. If you do not provide one, one will be generated by the node.

PatrickAlphaC · 2021-07-21T16:44:49Z

Looks like we need to add some migration examples in here.

@DmitryDao is this something you can do? Show JSON jobs and what their TOML equivalent jobs look like? If no one can, I can take this, but I'd much rather someone else if possible. Perhaps @ZakAyesh? How much node experience do you have?

thisguy002 · 2021-07-22T10:33:20Z

Looks like we need to add some migration examples in here.

@DmitryDao is this something you can do? Show JSON jobs and what their TOML equivalent jobs look like? If no one can, I can take this, but I'd much rather someone else if possible. Perhaps @ZakAyesh? How much node experience do you have?

I haven't really worked with TOML but I know there are converters for that. Just let me know which migration samples are you talking about and I'll see if I can do something about them. I haven't been working with nodes for a while now though so I might be out of date on the recent updates that are mentioned in these docs.

thisguy002 · 2021-07-22T10:56:34Z

+          { url: '/docs/jobs/', title: 'Jobs' },
+          { url: '/docs/tasks/', title: 'Tasks' },


Maybe we should call them Jobs V2/Tasks V2 and the old ones Jobs V1/Tasks V1 (at least in the navbar) temporarily? This will help people can move over gradually. Thoughts?

Yup that seems reasonable

Thinking about this more, I suspect it's likely to lead to more confusion. Since we have various v1/v2 of other things like ocr v1/v2 or VRF v1/v2. Better to keep the language here as it is

thisguy002 · 2021-07-22T11:02:33Z

+Please refer to the [V2 jobs page](/docs/jobs) for guidance on how to do this.
+


Do we think we should create a migration guide or tutorial instead of keeping deprecated docs? This is a big deal and people should be aware of it.

I am creating a migration guide to be included in this PR.

thisguy002 · 2021-07-22T11:11:38Z

+
+![DAG Example](dag_example.png)


This should be:

And can we create a task for the design team to create this image in the our brand style?

I can't figure out how to get this image to work.

thisguy002 · 2021-07-22T11:29:12Z

+## What is a Task?
+


I think the new version of tasks has to be updated on a few other pages:

Fulfilling requests

Bridges

thisguy002 · 2021-07-22T11:32:04Z

+### Direct request (eth log)
+


What's the replacement for RunLog in a new version?

This job type replaces both runlog and ethlog. There's a discussion around whether we rename it to ethlog as thats just a better/more descriptive name than directrequest

thisguy002 · 2021-07-22T11:36:39Z

 whatsnext: {"Introduction to External Initiators":"/docs/external-initiators-introduction/"}
 ---


Do we keep the External Initiators in V2? I mean not only here but all of the relevant pages/docs.

Yes External Initiators still exist and work with V2 jobs, they probably need a documentation overhaul though.

spooktheducks · 2021-08-09T07:51:17Z

Review pls

Co-authored-by: Alex Roan <alex.roan@hotmail.com>

StephenFluin · 2021-08-11T14:31:58Z

Closed via #292. Thank you for all of the excellent new content!

samsondav requested review from AnushV, PatrickAlphaC, StephenFluin and alexroan as code owners July 16, 2021 12:58

samsondav force-pushed the chore/ch12971 branch from 2eaac24 to cae24e0 Compare July 16, 2021 12:59

samsondav force-pushed the chore/ch12971 branch 2 times, most recently from de218b5 to c093093 Compare July 16, 2021 13:27

alexroan suggested changes Jul 19, 2021

View reviewed changes

samsondav force-pushed the chore/ch12971 branch from 524f10b to 03b568d Compare July 19, 2021 14:59

samsondav requested a review from alexroan July 19, 2021 16:30

PatrickAlphaC reviewed Jul 20, 2021

View reviewed changes

samsondav requested a review from PatrickAlphaC July 21, 2021 13:30

connorwstein reviewed Jul 21, 2021

View reviewed changes

thisguy002 reviewed Jul 22, 2021

View reviewed changes

samsondav force-pushed the chore/ch12971 branch from 22f2238 to 26e6ff7 Compare August 2, 2021 08:31

spooktheducks force-pushed the chore/ch12971 branch from f872c32 to b201006 Compare August 9, 2021 07:48

spooktheducks force-pushed the chore/ch12971 branch from b201006 to 6a7724f Compare August 10, 2021 18:42

samsondav and others added 9 commits August 10, 2021 15:54

Update docs to deprecate V1 and add basic V2 job

51dfcff

Rename

68a89c7

Nav

18cdb44

Update docs/Oracle Jobs/jobs.md

91cb5ae

Co-authored-by: Alex Roan <alex.roan@hotmail.com>

PR suggestions

08a8ab6

Add externalJobID, remove FM precision and VRF info

454cc81

wip

aa7012e

Add two migration examples

1b33f4a

Update specs

7268326

samsondav and others added 3 commits August 10, 2021 16:00

Add better docs for External Initiators

2c59b36

Update migration doc

1461cae

Update v2 job docs

25dde27

spooktheducks force-pushed the chore/ch12971 branch from 6a7724f to 25dde27 Compare August 10, 2021 21:03

StephenFluin mentioned this pull request Aug 11, 2021

Stephen/v1 jobspec deprecation #292

Merged

StephenFluin closed this Aug 11, 2021

		{ url: '/docs/jobs/', title: 'Jobs' },
		{ url: '/docs/tasks/', title: 'Tasks' },

		Please refer to the [V2 jobs page](/docs/jobs) for guidance on how to do this.

		whatsnext: {"Introduction to External Initiators":"/docs/external-initiators-introduction/"}
		---


		![DAG Example](dag_example.png)

Conversation

samsondav commented Jul 16, 2021

Uh oh!

netlify Bot commented Jul 16, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexroan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

PatrickAlphaC left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PatrickAlphaC commented Jul 21, 2021

Uh oh!

thisguy002 commented Jul 22, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samsondav Aug 2, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

spooktheducks commented Aug 9, 2021

Uh oh!

StephenFluin commented Aug 11, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

netlify Bot commented Jul 16, 2021 •

edited

Loading

PatrickAlphaC left a comment •

edited

Loading

thisguy002 commented Jul 22, 2021 •

edited

Loading

samsondav Aug 2, 2021 •

edited

Loading