[BLIP-3] Example, BRI and Integration Folder Structure

[humbitious]

Example, BRI and Integration Folder Structure

The current folder structure on the Main branch is confusing specifically when it comes to BRI (reference implementations), which you currently have to discover in the Examples folder, which makes no sense. And actual examples, like the hello world battleship game, you would have to discover inside yet another examples folder inside BRI-1, which makes it seem like it is only an example for BRI-1. And then there are integrations, like SAP, Dynamics and Excel. Integration libraries, we argue, should a) be independent of any given BRI, and b) should be found at the top level of the repo folder structure, so that they are easy to find, and so that others are encouraged to contribute more integration libraries to more things over time.

author: John Wolpert (@humbitious)

This BLIP is a proposal for a simple set of folder changes. The only test of completion is to see the correct folder structure as described above and to test that the new folder structure does not break anything in the code.

---

Copyright Copyright and related rights waived via CC0-Universal.

(This template adapted from the EIP template at https://github.com/ethereum/EIPs/

[skosito]

@humbitious As discussed, I will pick this up

[Therecanbeonlyone1969]

Proposal on Structure:

docs -> subfolders as required

reference-implementation -> subfolders one per reference implementations

examples -> subfolders one per example

.dependabot and .github should stay at the top.

@humbitious

[GoldenBit0]

@skosito Please see above proposal as well - do you have an update on your work with this? TIA

[skosito]

Thanks for proposal @Therecanbeonlyone1969 , @GoldenBit0 I will have some updates until Monday.

Couple of questions regarding proposed structure:

• docs -> subfolders as required - Could you please clarify what is required in the docs, and needed to be changed? Maybe rename docs/bri to docs/reference-implementation, to be inline with reference-implementation name change at top level

• reference-implementation -> subfolders one per reference implementations Does this mean we rename current "examples" folder to "reference-implementation"? Then we would have something like reference-implementation/bri1 (here we can remove bri-1/base-example layer I assume, and move it's current context to be directly in bri-1? What about bri1/lib, it contains 2 more reference implementations, should they remain part of bri1 or moved to same level as bri1) reference-implementation/bri2 reference-implementation/bri1/radish

-examples -> subfolders one per example If I understood correctly, currently there are no examples like hello world, battleship etc. that would be in this folder, so it would remain empty for now?

[skosito]

@humbitious @GoldenBit0 @Therecanbeonlyone1969 Hey, I pushed simple change here, please check if this makes sense on a folder structure level, it should be visible like this: https://github.com/skosito/baseline/tree/add-ref-implementations-folder Pretty much I renamed examples to referenced-implementations and then run bri-1 and bri-2 readme commands and checked if i get same results. I did not do any testing yet for remaining (deprecated radish34 and lib folder in bri-1) since they seem more involved for verification, but I will try verify as well - if you have some advice here, please let me know.

Then I cleaned up mentions of examples folder (mostly in urls) across codebase and replaced it with reference-implementations (I might revisit this and also leave examples folder in some .npmignore files since we will probably need it once we actually add examples folder again).

There is one more place that is referencing examples folder, in couple of json files in bri-2, but it seems like an local output of some tool (truffle?), in this format (this is Shield.json file in bri-2): "sourcePath": /Users/samuelstokes/repos/Web3Studio/baseline/examples/bri-2/contracts/contracts/privacy/Shield.sol. Do we need these types of files, since they seem connected to local build anyways?

Please review this and let me know your thoughts.

[humbitious]

Hey @skosito! Nice work! I took a look, and other than obviously needing to add a new /examples folder, looks right to me. Let's merge it. @bitwiseguy can comment on the json files in bri-2.

Let's be sure that Radish-34, if it isn't already, is solidly marked as deprecated...I think it is.)

[skosito]

@humbitious , thanks for checking it, I opened PR for this.

[GoldenBit0]

Maintainers to review/approve PR 432- https://github.com/eea-oasis/baseline/pull/432

[GoldenBit0]

12/13/21 Core Devs Session:

• Leaving open for 1 more week for Provide to determine if changes will be made (and time required) so links don't break or can leave as is.
• Andreas: need to register DNS and relative links, Sonal & Andreas will take offline

[GoldenBit0]

1/10/22 Core Devs Session:

• Low priority, important to assess
• No activity
• Andreas suggestion: archive repo and start over, so old links work and new one is done
• Andreas: Relative links mean you have forwarding. You post only the relative link in communications. This is how W3C does it. The relevant info to implement this is in the BLIP-3 issue. This will mean that relative links are new links and can be forwarded. However, old hard links will break. Suggestion is to achieve the repo and start over. That way the old links works, the repo is archived, and the new repo can start fresh with relative links.
• John proposal: New BLIP for implementing relative links and in top level readme add relative link steps

Outcome:

• Will not make change for few months to avoid links breaking, in future will use relative link standards that will have updated docs with instructions.
• blip or grant or designated resource to implement that, and that we don’t need to change the folder structure, so that the old non-relative links will still work for now, and that we add a comment in Readme to urge folks to use relative links.

[GoldenBit0]

5/2/22 Core Devs Call:

• Will reopen in next core devs call to finalize proposed changes.
• @kthomas @humbitious

[GoldenBit0]

6/13/22 Core Devs Call:

• @kthomas the folder restructure will be completed this month, any pending items or concerns? Thanks!

[GoldenBit0]

6/27/22 Core Devs Call:

• Final reminder for any concern in 24 hours, without negative consent will implement changes

[GoldenBit0]

@kthomas Hi Kyle, per the Core Devs call today, we are going to proceed with the folder changes. Please review if this will break any links or cause issues for you, and let us know by tomorrow.

Thanks!

[kthomas]

@kthomas Hi Kyle, per the Core Devs call today, we are going to proceed with the folder changes. Please review if this will break any links or cause issues for you, and let us know by tomorrow.

Thanks!

Thanks Sonal, I would like to see the PR and then I can comment...

[GoldenBit0]

7/11/22 Core Devs:

• Final updates will be made

[GoldenBit0]

7/25/22 Core Devs:

• Team is ready to move forward on these changes, need to determine if it is ok since BRI-1 will be moved out of example? Added as item for TSC
• Will need to decide if SRI work lives in examples of 'reference implementations'

[GoldenBit0]

9/19/22 Core Devs:

• suggestion: create readme that points to where sourcecode will live (correct wording and link)
• Ryan F to work with team to discuss

[GoldenBit0]

10/3/22 Core Devs:

• Ryan F update: Project team wants to update the references for BRI-1 to point to where they're being actively maintained and working (PRVD-OASIS & Provide Platform org), complexity because still migrating stuff into PRVD-OASIS
• Action: Sonal will follow up with Kyle, Ryan will provide an update

[GoldenBit0]

10/17/22 Core Devs:

• Ryan F: update pending from team, Ryan reviewed PR from earlier this year to make changes and facilitate completion of PR.

[GoldenBit0]

10/31/22 Core Devs:

• Reference implementations and examples should be separated
• PR will be submitted to instantiate change and complete work outlined here

[GoldenBit0]

11/14/22:

• Consensus amongst group to have RI's apart from examples folder
• Proposal to wait until BRI-3 is complete to change folder structures - majority approved