Detailed example attribution

[ksen0]

Addresses #415 - work in progress. Remains to be done:

• Support for cases where pre-2023 attribution is also collective e.g., Shape primitives
• Support for cases where there is no link for author
• Once done on main, will need to be cherrypicked to 2.0 as well
• Ensure all people mentioned in any part of attribution is on all-contributors in p5.js README in both main and dev-2.0 branches and include "example" emoji. Complete list: Prof** WM Harris, GH/prashantgupta24

Curent Behavior

The license is at the bottom of the page, and attribution (inspired by and maintained by) is split.

(Then there is the sketch and the code - viewer has to scroll all the way down)

PR Behavior

Considering showing the attribution more clearly. "p5.js Contributors" also points to all-contributors list in p5.js repo README, rather than the People page. The screenshots includes rephrasing to increase clarity for each example but make the history more maintainable overall using a clearer schema; this is also open to feedback.

Future use

Although attribution of p5.js contributors work is collective, this schema allows detailed attribution of referenced work from outside the community. For example, including the following in the .mdx of an example:

remix:
  - attributionLabel: Processing example by Ira Greenberg
    attributionURL: https://processing.org/examples/reflection1.html
    remixLabel: Based on
  - attributionLabel: David Blitz
    remixLabel: Ported by
  - attributionURL: https://github.com/dkessner
    attributionLabel: Darren Kessner
    remixURL: https://github.com/processing/p5.js-example
    remixLabel: Revised in 2023

collectivelyAttributedSince: 2024

Will create the following attribution:

Thus, new examples can be added that correctly attribute referenced material. In the above schema, the collectivelyAttributedSince field is applicable mainly to examples ported from the Processing or archived p5.js site. For future additions, the remix filed can be used to provide a complete history. The URLs for attribution and type of remix can be edited, with optional URLs. If there is no remixLabel, "Remixed from" will be used, but other phrasing can be provided for clarity.

[calebfoss]

@ksen0 This looks great! I really appreciate the thoughtfulness of how you put this together.

One tiny tweak: it occurred to me that since the code was copied over to this repo in 2024, it should be "2024 onwards" rather than 2023.

This certainly does not need to be in this PR, but something to consider for the future: I think it would be helpful for readers to have some visual design distinction between the description and attribution. I'm picturing the ways that text publications design attribution information in articles. Italics is a common convention but may look awkward with this much text. Maybe just a slightly different background color?

Thank you again!

[ksen0]

Hi @calebfoss ! This is ready for review. I've updated the 2023 to 2024, and created some flexibility for attribution copy in the schema, happy to hear your thoughts.

Maybe just a slightly different background color?

That seems like a good idea, I will look into that (background color and/or italics), but opening the functionality for review now. Do you think using a slightly smaller font can be an option too or does something speak against it?

Also: I'm not totally sure how to correctly indicate Malay's work in some of the examples (Alpha Mask, Sine Cosine, Aim). Color Wheel and Lyrics Poem does attribute Malay but I wasn't sure on correct attributionLabel and attributionURL to use.

[calebfoss]

@ksen0 thank you again for your work on this!

Here are the issues I found:

• Color: missing credit for @dkessner and me
• Conditions: I don't think "remixed" is the best word here, since this shares no code with Prof. Harris's example. Rather, it was intended as a completely new example inspired by the educational intentions of her example.
• Alpha Mask: missing credit for @Malayvasa
• Audio Player: I wrote this one from scratch, but it currently credits @katlich112358
• Video Capture: missing credit for @katlich112358
• Translate: missing credit for @dkessner
• Color Wheel - missing link for @Malayvasa
• Noise - I wrote this one from scratch (missing credit)
• Random Poetry - missing link for @Malayvasa
• Sine and Cosine - missing credit for @Malayvasa
• Aim - missing credit for @Malayvasa
• Circle Clicker - I wrote this one from scratch (missing credit)
• Ping Pong - I wrote this one from scratch (missing credit)
• Custom Geometry - @davepagurek wrote this one if he would like credit
• Filter Shader - @davepagurek wrote this one if he would like credit
• Adjusting Positions with a Shader - I think this is @davepagurek too?
• Multiple Canvases - I wrote this one from scratch (missing credit)
• Local Storage - I wrote this one based on the @shiffman JSON and Table examples (missing credit)

Across the examples, none currently link the code on GitHub for the original site version or the 2023 revision version. The 2023 revision link points to the 2023 repo, but not the specific code. As we discussed in #415, linking the specific code from both the p5.js-website-legacy and p5.js-example repos provides a path to the git history, which documents many more contributors' work.

I am really happy to see this getting close to completion! Thanks again!

[davepagurek]

Those ones you tagged me on are ones I made, yep!

[ksen0]

Hi @calebfoss , thanks for the detailed list! While working on this, I'm trying to keep maintenance in mind, too, and the next commit is WIP but below is a question I have in terms of design, if you have any thoughts on the below please let me know!

As an update, I added support for multiple attributions in one remix line ("Revised in 2023 by PersonA, PersonB") so the missing attributions will appear in the next iteration. With that I can cover all the missing credit cases. Not yet committed to PR, but here's an example of .mdx syntax in case anyone has input:

remix:
  - description: Revised in 2023 by
    attribution:
     - name: Caleb Foss
     - name: Darren Kessner
    codeURL: TODO - specific example code goes here

(There's a lookup, attributionURLLookup in config.ts replacing what's there now but making repeated attributions easier to maintain. If no URL is provided, one from the lookup is used; otherwise, name is not linked. So it's still really flexible.)

I also updated the phrasing or "Remixed from" -> "Inspired by" of the Conditions examples, but for the structure as a whole, from what I understand, "remix" has the widest applicable meaning in modifying and building on open source code in many different ways (example usage in an analysis of sketches). Unless there is another similarly flexible alternative, I'd like to keep this usage, at least under the hood. (Because this schema is pretty complex, I'll also be adding some contributor guidelines on using it when this is more defined.)

I've been trying to figure out a way to add the code links to the two repos. Please let me know if the two links in the blow example don't meet the criterion! (EDITED to reflect slightly renamed fields in an attempt to improve readability)

remix:
  - description: Inspired by
    attribution:
      - name: Prof. WM Harris
        URL: https://people.rit.edu/wmhics/
    codeURL: https://github.com/processing/p5.js-website-legacy/blob/main/src/data/examples/en/04_Control/05_Logical_Operators_2.js
  - description: Revised in 2023 by
    attribution:
      - name: Caleb Foss
    codeURL: https://github.com/processing/p5.js-example/tree/main/examples/02_Animation_And_Variables/03_Conditions
  - collective:
      - since: 2024

Option 1

Less legible because too many links and unclear where the "inspired" and "revised" links go:

Option 2

More legible, however there are some challenges with this:

I think if at some point these links become inaccessible, then it's possible to easily identify, remove, or replace with wayback machine versions where possible, so this seems alright, but please let me know if you see any other potential maintainability issues.

Potential issues with option 2:

• Non-descriptive label of "code" link. Possible ideas here would be "code in p5.js-website-legacy repository" but this makes the whole block potentially less readable. (Still better than option 1 above, though, I think?)
• Inconsistency: lack of matching "code" link for the last part that describes current maintenance. Could be added technically, but given the strong concern with maintainability in Creative Commons License Violations on Examples #415, unless it addresses the specific current attribution problem, then I really hesitate to add it.

Anyway, I'm still working on this, and I'll update here if I have a different more compact (in terms of schema and template layout code) solution, but in the meantime I wanted to share in case you had thoughts on this!

[calebfoss]

Thanks for the update @ksen0!

I'm with you on Option 2 looking like a better direction. The word "code" tells me what to expect by clicking the link. To make the link more clear out of context for accessibility without getting too verbose, perhaps pre 2023 code, 2023 revision code, post 2023 code?

Regarding linking the current code, I think of the message included at the bottom of Reference pages:

Notice any errors or typos? Please let us know. Please feel free to edit [link to code on GitHub] and open a pull request!

I would expect this to improve the maintenance process, as it invites the community to help without having to sift through the GitHub repo searching for the matching file. If you had the current GitHub code path in the MDX, you could consider reusing it for both the attribution section and an invitation to help that matches the reference pages.