How could I (better) contribute to three.js


#1

Are there any other general rules and guidelines on three.js contribution other than this?

This covers only the technical aspect, i’m looking for etiquette, best practices, post format and such. I write lengthy posts with lot’s of (pseudo) code, and I some times get passionate. This has the undesired effect of people just ignoring you :slight_smile:. I’m looking to improve this if there’s anything to improve.


#2

When contributing to a project, it’s in general a good approach to be brief. Writing endless posts is no good idea even if you provide a tl;dr version. It just feels overwhelming so developers invest their time in other stuff. I think it’s important for a PR that is benefit is clear in at most two or three sentences.

I personally do not tend to explain code sections unless somebody is asking for it.


#3

What if something is too complex and requires more explanation, could it be argued that thorough conversation may help catch bugs or dial in patterns?


#4

What do you mean when you say “explain code”?

I noticed you spend time answering questions on SO but having been down that route myself i’m concerned with how it impacts three.js given that you in particular are a maintainer.

When I got fed up with SO i decided to spend my time writing PRs, but as a random user my PRs are not visible. When you as a collaborator decide to not spend time on PRs but instead direct it on SO it feels a bit unproductive as far as three.js goes.


#5

As an example, you just wrote two replies to a single simple suggestion. Keep things brief and use live examples / screenshots instead of words where possible, and only write one reply at a time.

As @Mugen87 says, people are really busy - I’ve come across your recent PRs on github, and even though they look interesting I’ve seen how long your posts are and just skipped them. It’s nothing personal, just limited time and I would say that I’m not the only person feeling this way.


#6

@Mugen87 would have a little bit of extra time if he skipped responding to this SO question..

This question appears every 10 days. I usually just remove the three.js tag and write something very similar as @Mugen87 wrote (go read the f manual). The idea is that people whos time is valuable doesn’t waste that time over and over again by answering the same question on SO.

(Kinda harsh sounding)


abridged version of the post:

@mugen87

Please stop wasting time answering useless SO questions, you’ll have more time to look at some of the open PRs, there’s a lot of them.

(this feels like it reads suuuuuuuuper harsh)
(actually confirmed, very rude)


As @Mugen87 says, people are really busy - I’ve come across your recent PRs on github, and even though they look interesting I’ve seen how long your posts are and just skipped them. It’s nothing personal, just limited time and I would say that I’m not the only person feeling this way.

@looeee
How do you get familair with three.js without reading the massive codebase? Do you have any advice here?

Don’t read just look at the lengths, same thing:


This is the exact same things, in 10791 i say

heres a pr

in 14031 i wrote a project doc as i would for my job

Neither seem to have worked, although i see what you’re saying, the “heres the PR” one did get comments but did not get accepted.

The one with the project doc i think would be harder to reject, because it strives to make valid arguments but no one is reading it.

What is the solve here, what is the sweet spot?

I just looked for the next thread that has a lot of comments and found you in it. I’m just glancing at it since it’s long, but it doesn’t sound like a specific problem is even outlined here. Overall it’s more text than i put in my project doc single post.

Could a solution here be to get a cohort? Instead of one person writing a long post, i could get a few friends to “add their thoughts” and make it seem like a discussion. It would be the same thing, but it seems like it would be easier to read?

To reiterate, i’m not judging, we’re all human beings free to do whatever we want. I’m interested in the process, improve what i can of the process and myself, know how to identify a battle that cant be won etc.

Would it be ethical to start offering incentive? Like

I’ll buy you a beer if you help me digest the wall of text in my last PR request.

Or

Hey man, i’ll send you $100 on paypal if you can spend 10 minutes to read one of my posts. I’m really trying to improve my communication and learn how to better write software docs.

Meh, another wall of text, made worse by how discourse parses these github links.


#8

@looeee
I have added a very short post with an overview, and a disclaimer that the second, longer post is an optional read (in a PR i made).

and even though they look interesting I’ve seen how long your posts are and just skipped them.

Here my important take away is the word post. If one post is too long, no matter how it’s structured or if it uses headers, sub titles and such, you wont read it? If github had something like [spoiler][/spoiler] it seems like it would solve my woe :frowning:

But i’m afraid multiple posts are also a problem.

Alternatively i can think of writing the entire idea somewhere offline and then feeding portions of it in single short posts, but only if someone replies?


#9

You learn alot by reading the patterns/styles from others as they answer to questions with what I’ve been discovering from: Github, Stackoverflow and Discourse - @Mugen87, @Fyrestar, @looeee, @prisoner849

True I’ve had to read hundreds of posts, I hardly get bored reading about all the things you can do with Three.js + how others are pushing the envelope or to improve the platform.

From what I’m experiencing what is the knowledge level/capabilities to how well a dev(s) can articulate their answers + code examples to the community. Truly amazing to keep this kind of momentum going!

On another note I’ve been discovering: after reading many posts at least in stackoverflow you do find many Three.js examples are broken. We as a community possibly should try to help those to update their scripts across the board. Maybe I or another dev create a discourse page to support how to go about fixing those scripts.


#10

@ben any thoughts here?


#11

I see the concern and that even for myself would take some time to break down to understand what is all happening here. It is true from the title this should be able to explain it all.

With all the Pro(s)/Con(s) in the optional read it is a weight and measure system with Three.js that would need to be discovered further even though you have done the discovery work to breakdown for another dev this is an understanding of effort to the future benefit. Maybe their is a side effect or another plan you are unaware of.

You know they say a picture is worth a thousand words. This helps to break up the content and usually most humans are geared for visuals faster than digesting lots of content!

Hope this helps with more thinking surrounding your question(s).


#12

I kinda see what you’re hinting at but i didn’t quite understand it. Are you saying it’s ok to do due diligence and provide the extra information ahead of time? Or are you saying it will hurt the process?

I don’t see this being done in the past, which is how three.js ended up with a feature that no one uses.

I don’t understand the balance there, in my book to give as much info as possible ahead of time is good. What is the equivalent of a picture in our world? Is the refactoring example good (foo - 130 lines, bar - 160 lines, baz -20 lines etc.)? I also changed the title 4 times, which do you think is best, or is there a better one for this particular case?

I best learn from examples :slight_smile:

I do notice that i got more responses when i initially filed the same thing, which was just

Here’s a PR

The additions though seem daunting in this one ^


#13

I’d have to read more of your github post(s) to understand your personal pattern.

With Material includes entails quick wins. When I see mr. doob respond West Langley is not far behind in making sure either the thinking is aligned or they are identifying other relationships to Three.js.

Time frames when responses are happening is key as well.

You are correct in providing information but when the conversation appears long winded can that be summed up similar to rebasing in github history with squashing I think is where the guys are getting at because like you said you changed the title 4 times. Can this be done with your postings or are they all necessary?


#14

Well I’m experimenting with titles, do you think one of these 4 is better than the others?
I’ve specifically wanted to illustrate a demo here with code.

Also I won with the first one getting comments but failed to get the actual code considered.


#15

I also tried breaking down the wall of text into several issues but not sure if that’s a good approach either.


#16

Well, the problem as I see it is that you are writing walls of text in the first place. It doesn’t really matter if they’re broken down into multiple replies, most people are just not going to read them.


#17

“Don’t write walls of text”?

Is there a generally accepted criteria that defines what is and what isn’t a wall? I know it’s subjective but I also know when it’s objective :slight_smile:


#18

Most are going to bail on the conversation we are currently having at post 5 unless they are really curious or invested as we are in what appears to be defining the standard. When at the top of this conversation with @Mugen87 and @looeee they have already answered your question.

What I think you are seeking is either:

  • getting more answers from the community to respond to this topic
  • this has been going on for a while and realizing all the time you are losing in trying to get your point across isn’t working
  • someone has blatantly pointed this problem out and your confused because it worked in the past why can’t posting as I do work again - old habit(s)/condition(s) are hard to break

FYI
When I retrospect my own postings I do usually delete what is no longer relevant - saves on the thread. Which would appear in this case an intentional hit to prove the point further but I won’t this time. It would only make your posting wall appear larger and harder for our readers to follow unless you begin purging as well - this can happen based on stagnant/irrelevant data as to where this conversation is going.


#19

I am super greatful for any feedback. I’m more trying to make sense out of it all and think I’m doing something wrong, and it’s a downward spiral from there. :slight_smile:

Well thank you


#20

I’m actually making a platform providing an “asset store” kinda for THREE, also to introduce projects made with it to showcase and to team up.

Also for other resources like books, they are categorized. Fiddles and pens can be created in categorized examples, libs can be linked to Github or uploaded directly. Any kind of asset is rather structured with attributes, not like a plain forum post for example.

It also provides a typical board forum, though i don’t know if this forum interferes too much with discourse. Discourse still is less of a community platform, rather a basic team forum in my eyes. I’ve added several features such as for moderation, mentions, subscriptions and also picked up the idea of a glossary, which will link the terms onces used in posts.

I think it could help to provide a place where the rather scattered resources, examples, libs and also actual projects made with THREE can be found.


#21

The forum is the old bulletin board(BB) system. Discourse in my opinion is the modern thinking of the BB.