terms from issues p1

[Christian-MK]

These are terms which have been proposed in Issues

---

Closes #11
Closes #31
Closes #5
Closes #22
Closes #32
Closes #39
Closes #12

[Christian-MK]

From @waalge

I can't sign off on these definitions.

These are general terms for which i am not aware we have any meaningful divergence from how they are generally understood. At worst I think we should cite external sources for them

API came up over as an issue cos there was disagreement over whether using the blockchain for the interface was an API, since it is more commonly used to refer to HTTP interfaces. (The answer is that it is unambiguously an API as API does not require HTTP.)
The definition given doesn't resolve the disagreement, and i don't think is nearly as clear as the one provided by a dictionary.

The criticisms in this comment are general and I'm unsure if totally warranted. These terms are being pulled from Issues where they have been proposed/reviewed for some time; your absence in the comments was mistaken by me as implicit acceptance.

Please identify explicitly (like you did with API) which terms you wish to critique and follow this with solutions/edits. If there is a divergent or nuanced definition that would make a general term more understandable within the Orcfax context, let's draft it.

[Christian-MK]

Terms included in the last commit:
function #5, consensus #11, trustless #12, oracleProblem #22, dataSource & PrimaryDataSource #31, sourceDataPoint #32, and triangulatedDataPoint #39

[waalge]

I've to many opinions to share them at every potential opportunity. I'm not product owner of the glossary. I don't dictate what goes in. I put in the things I think are important. Consumer. Integrator. Feed id. Statement. These are orcfax specific. It's important to me we know and agree what they mean. You can't look these up anywhere else.

I just said I can't approve any of these definitions because I'm not aware of anyway any of them diverge from a commonly understood definition. API? Just look it up.

It doesn't mean someone else can't review and approve this PR.

[ross-spencer]

@Christian-MK @waalge the need for API goes back to June: https://discord.com/channels/918870284331802674/1007406724346548395/1252632943365718036 -- I wonder if it's not so much API doesn't fit here because we can look it up, but whether we just need to work on the definition some more, for example, Peter calls for us to make it clear "we will always mean x when we use term y" <-- I was probably a bit skeptical, but as an example, we can say:

• API is... something something HTTP endpoint
• An API could also be... reading something from on-chain
• API will always mean the former at Orcfax
• Another term will be used for the other methods, e.g. see consumer

I can see some value in adding the extra context. How does it sound to you?

I don't think I'll have capacity to go into more detail on these today, but will circle back this week as best i can.

[waalge]

How does it sound to you?

I am still against its inclusion. I really don't see value in orcfax trying to commandeer the term "API" distinct from its general use. That is perhaps until the point where there is an actual 'product' called 'orcfax api' or similar.

But also still, this not a hill for me to die on. If people want it, they can review and confirm it.

[Christian-MK]

@waalge I have removed API for further discussion.
Are the remaining terms good for me to merge?

[waalge]

@Christian-MK . No. See previous comment

I just said I can't approve any of these definitions because I'm not aware of anyway any of them diverge from a commonly understood definition. API? Just look it up.

API was just an example that partially qualified as "something to be put in the glossary" since there has been divergent understanding of what it means. I say partially, because as far as I'm concerned we should use it exactly as its generally understood ie the definition that appears when you google it. And for this reason should not be in our glossary.

Also in the previous comment

It doesn't mean someone else can't review and approve this PR.

[Christian-MK]

@ross-spencer given the previous comment, would you please do the review?

[ross-spencer]

Trying to find the middle path here as we approach release and want to point to things like the glossary, I do appreciate the effort to add these terms and add them and personally think they will largely benefit us. We should also try to revisit the philosophy of the glossary at some point and determine whether generally accepted definitions work for some things over others.

I do see both sides in API but perhaps there are more examples we can find that can anchor a useful discussion.

We can always remove terms in future if they become unhelpful.

We rarely have an excess of capacity in our team but I was reminded today about the communication artifacts of empathy driven development and remembered I had outlined their use in our code-review guidelines: https://github.com/orcfax/code-review?tab=readme-ov-file#comments-and-communication -- I feel like in the case described above the principle of more communication (and disambiguation) across the team and team boundaries would probably mean electing to merge the definition. Whether it is the right approach to the glossary is a different matter, and whether the glossary truly satisfies what we need in a domain model another; but we should bring it back to the table in the future and discuss.