update and cleanup contributing guidelines

[ziyuan-linn]

WIP guidelines for standardizing the API across different ml5 models

[shiffman]

@myrahsa this pull request is a draft of a "contributing" guide to the codebase of ml5.js that @ziyuan-linn is working on. This is something that aligns with the work you are proposing to do around a "style" or "language" guide (apologies if I am mis-stating this) for contributing documentation and other materials. Your work could be incorporated into this document, a separate document, or both!

[myrahsa]

Thanks @shiffman! I'll start putting together my work throughout the week and see if this will work for my purposes.

[shiffman]

Hi @ziyuan-linn, apologies for losing track of this. I'd like to merge this wonderful additional documentation! Can you take a look at what is conflicted and let me know when I can review again?

[shiffman]

@ziyuan-linn thank you for working on this! I've made some light edits for clarity and style, take a look and let me know if you have questions! I'll merge after you do one more pass? Thank you!!

[shiffman]

Suggested change

	8. Asynchronous ml5 functions should support the callback interface, and support the promise/async await interface as well when possible.
	8. Asynchronous ml5 functions should support the callback interface, and support the promise/async await interface as well when possible.

Are we supporting promise/async/await with the models? maybe this should say something like. "The ml5.js models do not currently support promises (async/await), however, we are considering adding this in the future and plan to follow the p5.js's lead."

[ziyuan-linn]

Most of the current code does support the promise interface when possible. Perhaps we can say something along the lines of "Although some existing code has both callback and promise interface, the ml5.js models do not currently support promises (async/await) officially, however, we are considering adding this in the future and plan to follow the p5.js's lead."

[ziyuan-linn]

@shiffman Thank you for the review! I will take another look. Do you think it would make sense to break up the contributing guide into multiple documents? Perhaps we can have a guide for any contributor and a guide for maintainers/ ml5 devs. We could also break the API guideline into a separate document. The documents can also link to each other as additional resources.

[shiffman]

@shiffman Thank you for the review! I will take another look. Do you think it would make sense to break up the contributing guide into multiple documents? Perhaps we can have a guide for any contributor and a guide for maintainers/ ml5 devs. We could also break the API guideline into a separate document. The documents can also link to each other as additional resources.

Let's finish and merge this first and we can think about breaking it up as a separate step? Also, I wonder what, if anything, from here should be on the website? Perhaps a link to here from the FAQ? cc @MOQN @QuinnHe

Let me know when this is ready for one final review and merge!

[QuinnHe]

@shiffman Thank you for the review! I will take another look. Do you think it would make sense to break up the contributing guide into multiple documents? Perhaps we can have a guide for any contributor and a guide for maintainers/ ml5 devs. We could also break the API guideline into a separate document. The documents can also link to each other as additional resources.

Let's finish and merge this first and we can think about breaking it up as a separate step? Also, I wonder what, if anything, from here should be on the website? Perhaps a link to here from the FAQ? cc @MOQN @QuinnHe

Let me know when this is ready for one final review and merge!

Yes, we have a dedicated page for contributing notes. We can update the content there accordingly! cc @MOQN

[shiffman]

Hey all, this is looking great! I think I should merge this so it can be shared at today's meeting! We can make additional changes and updates in new branches. Thanks all!