Confusion over discussions (in wrong repos, offtopic comments, etc.)

[DanRathbun]

I couldn't find the original thread in which Thomas mentioned something,
(a bit offtopic,) so I just started a new one to talk about link styling.

This thread is redirected to discuss confusion over discussions
(because like the other discussions, it was yanked offtopic!)

[jimfoltz]

I couldn't find the original thread

I'm honesty having a hard time following any and all the discussions going on the the issues. I have to go through several issues in several repos to find what I wanted to review.

[DanRathbun]

This thread is redirected to discuss confusion over discussions
(because like the other discussions, it was yanked offtopic!)

[DanRathbun]

Yes, Jim, it can be confusing, because GitHub gives us so many places to comment.

1. 1st problem is the HTML "docs" repo. This repo doesn't do anyone much good at all. (Unless they wish to just copy all the pages to their local drive. But, then the pages could be packaged up in a zip.)
But this was before the stubs were setup to be the "working repo" for the API documentation. So most the doc bug issues there need to be migrated to the ruby-api-stubs repo.

As noted below, the online docs are served right from GitHub.
(I thought they were copied to a Trimble server. My Bad!)

2. Anything discussing, or promoting ideas for the styling and functionality of the http://ruby.sketchup.com/ needs to be migrated to the sketchup-yard-template repo.

3. And then the ruby-api-docs repo removed.

Okay, so the docs repo is needed.

Perhaps the people who are not familiar with YARD syntax, nor GitHub protocol, can log issues in the docs repo. They will have no idea which (or why) of the other two repo (projects) that the issue, bug, or feature request applies to. This is understandable. So it is a buffer tracker.

Then one of the stubs or template repo contributors can migrate it, or rewrite it in the proper form as a specific stub change order (or orders if neccessary,) over in the appropriate "parent" repo.

Nitty implementation details can be debated in the 2 "parent" repos, where the doc consumers would likely not read, nor understand the YARD internals discussed if they did.

4. Then issues and discussions need to be put and stay, in the proper repo.

5. Replying to comments, issues, pull requests, etc., ... Need to stay on topic.
Otherwise start a new topic, or issue. This is especially true for issues and PRs.

(Everyone so far involved has been guilty of meandering offtopic, I as well.)

[thomthom]

1st problem is the HTML "docs" repo. This repo doesn't do anyone much good at all.

That's actually where the Ruby API docs are served from, we are using the GitHub Pages platform.

What we can do is set up Issue tracker template that contain information and guidance to what issue should be filed where; https://github.com/blog/2111-issue-and-pull-request-templates

Everything right now is rather new, but as we work out the format of all this things will settle down.

[DanRathbun]

So, whilst on the topic of "offtopic confusion", I asked nicely if we could cleanup the offtopic noise you (Jim) created in PR#10. Ie:
SketchUp/ruby-api-stubs#10 (comment)

We cannot be doing this in PRs! A PR needs to be requested against a specific Issue or Issues. It then needs to stand up to the test of whether it satisfies these open issues, and NOTHING MORE.

Otherwise, we never get anything merged! And Issues will grow and grow and grow, and never end.

The best Issues and PRs are small concise ones. These are ones that Thomas will be able to REVIEW quickly, and get merged. The bigger they are, the longer it will take, the more likely he'll get interrupted and lose his place and train of thought. (And probably have to begin again, later.)

This is like basic Engineering 101 - Drawing Change protocol.

The GitHub Issue is a like a DCR. Assignment to the drafter by the Documentation Manager. Pull Request is like a request by the drafter (to the Checker) to publish the changes they've made. The Merge is like the distribution of an ECN with prints, by the Configuration Manager.

It is not allowed to add NEW changes in at step 4 by the Checker, if they are not on the DCR. (Otherwise the whole process would have to stop and return back to the engineer who originated the DCR. Then resubmittal to the Doc. Mgr., reassignment to the drafter, request again to the checker, loop dee-doopdy.)

[DanRathbun]

I asked nicely if we could cleanup the offtopic noise you (Jim) created in PR#10.

Never mind I redacted PR#10. (I didn't put in it it's own branch, nor the next edit, and they started appending to one another, because both were from master.)

[DanRathbun]

@jimfoltz: I'm honesty having a hard time following any and all the discussions going on the the issues. I have to go through several issues in several repos to find what I wanted to review.

Ah Ha! I learned something a min ago, by accident.

Go to your GitHub homepage.
Scroll down to the Contribution activity section,
Beneath this are expandable sections with expandable subsections.

[DanRathbun]

@jimfoltz And here's another way of getting at "your stuff"

Click the bell icon at the upper right of any page. This is the notifications page.
You can filter by "Unread", "Participating" and "All"
When "All" is selected, you'll see each repo in which you're participating in the content pane.
You can reduce this by clicking the individual repo filters in the left column (which shows the tally of issues and Pulls, etc., you're involved with.)

You can also switch to the "Watching" tab, to get at the list of all repos you've clicked the "Watch" button on (anywhere on GitHub.)

[jimfoltz]

Thanks @DanRathbun, that's helpful. The other problem is staying on topic... some things I wanted to look up have nothing to do with the title of the issue. I go off-topic too often myself.

I went another route - you can add .atom to many GitHub URL's and get a feed for that url. Works for users, commits, releases, etc so I now have a nice aggegated feed of nearly everything that happens.

[DanRathbun]

Currently stuff comes into Gmail, like chained convos, that are missing any post I first view on GitHub. So they are not complete chains. And can be confusing.

I'd be better to just get a "busy" post, like a tweet that I have notifications, rather than a bunch of separate emails.