Community PR's

[NoahBres]

What is the Tech Team's stance on community PR's? Not encouraged? Encouraged? (ignoring all the accidental upstream PR's)

If they are encouraged, is there a way to get feedback on ideas before working on them?

If they are not encouraged, what is the recommended route for community suggestions? I'm assuming it's just the issues page right now. Is it possible to get official feedback on whether issues have been read, acknowledged, chosen for action, etc?

[NoahBres]

To add to this to possibly facilitate any future conversation:

I am aware that obviously the community cannot contribute to the internal FTC SDK. Even contributing to most of the RC code is not quite possible. All the new SDK features are committed with large diffs so I'm assuming some patch file is generated from another repo or something. And we cannot touch the aars.
However, I was looking at the README.md in the external/samples folder and thought it would be great if the README in the external/samples folder had a list of the all the sample files and a description of what they did. At this moment, a user needs to click every single file to find a specific implementation example. Also it would be great if the root README actually mentioned the samples! It isn't abundantly clear and many people do not know they exist. I am just using both of these as examples. Both should be a relatively trivial contributions or suggestions.
However, at this moment, the Tech Team does not have any officially endorsed channels where users can submit suggestions and receive feedback on them. The two previous examples don't quite seem appropriate as an issue as it would simply add noise to legitimate issues. It would probably be great with tagged issues. If the Tech Team officially endorses issues for suggestions then that is the route we will take.
However, if that were the case, feedback on various issues would be very much appreciated. Users are left in the dark and unsure of whether past issues are being worked on or even seen (see confusion with #90 ). It would benefit y'all as it reduces duplicate issues and provides insight into the status of various issues or suggestions rather than feeling like one is blindly yelling into the void.
In addition to that, documentation such as the wiki would most likely benefit from user contribution. Although even maintaining and approving such contributions is quite the hassle so I do see the struggle to support that.

We appreciate y'all's work! Thank you so much!

[AlecHub]

Good questions. There is probably a utility that generates a README.md from comments/tags in the source files in external/samples. Fyi, teams have been offering to assist FIRST in creating robust up-to-date online documentation for quite some time. So far FIRST has had no interest in this. So this should give you an idea of what the level of interest will be regarding the rest of your comments.

[gearsincorg]

Hi @NoahBres

As the curator of many of the original samples, I have a strong interest in people using them. So I am very interested in your feedback.

In the early days, all of the various tutorials and guides focused on pointing folks to these code samples and explained how to use them.
This did originally include the main project Readme, but as you have pointed out, they aren't mentioned there any more, which is clearly a big omission. I'll take on the task of correcting this specific problem.

When the first samples were originally created, I championed various naming and usage conventions for then, to make it very clear what each of them do. These conventions were/are documented in the readme in that folder (as you mention) and they are still in place.

I would say that it would be enlightening to click on every sample, and read the comments to see what it does in detail, but I don't agree that it is required to "click every single file to find a specific implementation example." There might be several samples dealing some of the more sophisticated concepts, like vision processing, but I would hope that most of the sample names make it pretty clear what they do.

I can see the potential value of a single list that elaborates on the contents of the samples. I do suspect that in many cases this will end up just being a more wordy expansion of the sample's name (with a lot of repetition and little more information). However, for those examples which are more elaborate, there would probably be a payoff.

That being said, creating the list, and then maintaining it's accuracy (as samples are added and changed) would be time consuming and tedious. So as a volunteer, it's not very appealing to me (being purely selfish in nature :)

However, it's one of those things that are reasonably self-contained, and does not effect the ever changing codebase. So it would be the ideal thing for another volunteer contributor to create to add value to the SDK and user experience. It's also one of those things that can created and published external to the official SDK, and then brought to the Tech Team's attention.

If it proves to be valuable to the community then I'd be eager to have it included officially. Note: this is how many community contributions get in the SDK.

:Edited for typos.

[NoahBres]

I'll take on the task of correcting this specific problem

Thank you so much!

When the first samples were originally created, I championed various naming and usage conventions for then, to make it very clear what each of them do. These conventions were/are documented in the readme in that folder (as you mention) and they are still in place.

I do most certainly appreciate the explicative names and I believe the naming convention works great.

I would say that it would be enlightening to click on every sample, and read the comments to see what it does in detail, but I don't agree that it is required to "click every single file to find a specific implementation example." There might be several samples dealing some of the more sophisticated concepts, like vision processing, but I would hope that most of the sample names make it pretty clear what they do.

I believe the underlying issue is primarily discoverability. For those who are experienced with the FTC SDK and have prior experience with programming in general, it may be trivial to find the exact sample you need. But for those who are new, knowing what to look for in itself is a challenge. The naming conventions are great but they may not be inherently intuitive to someone who doesn't have extensive experience with public API's. Especially younger kids. In addition to that, simply presenting a list in GitHub's interface isn't the most readable interface. And it most certainly is not the most accessible. Primarily in that there is no good way for these files to show up in some consolidated search result somewhere. For example, when teams want to learn how to use their REV Blinkin driver, they often have no clue where to start. If one were to google "programming rev blinkin FTC," the search engine cannot surface the particular file in the SDK. REV's Blinkin overview YouTube video and their documentation show up in the search results but that isn't FTC specific and only details PWM control rather than any of the SDK's available API's for the Blinkin. The only reason that I am able to point people towards the relevant SDK sample is because I happened to spend time reading through every example. Perhaps the file names are clear to those that are familiar with FTC jargon but to those who are not, it isn't. Most people who are getting started don't know what a "VuMark" is so I don't think one should assume that "ConceptVuMarkIdentification.java" inherently holds meaning, especially when there are no mentions of what a "VuMark" is in game manuals 1 and 2*. The only mention that I can find is the FTC GitHub wiki and I find that to lack proper discoverability as well. Thus, a README or just any other location that expounds upon specific details would be beneficial.

That being said, creating the list, and then maintaining it's accuracy (as samples are added and changed) would be time consuming and tedious. So as a volunteer, it's not very appealing to me (being purely selfish in nature :)

I 100% understand the issue of time and resource allocations, especially for volunteers. I really appreciate y'all's work. However, I do believe it is indicative of FIRST's commitment to creating polished and accessible documentation, which should be a necessity for any learning program imho. Of course am I not saying that the Tech Team volunteers should divert resources to such things. Money is the solution to this problem. Which is a somewhat naive statement without context but is not entirely detached from the truth.

If it proves to be valuable to the community then I'd be eager to have it included officially. Note: this is how many community contributions get in the SDK.

The official process for community contributions was the original question so I am assuming this will be discussed eventually.

Edit: Actually, I have realized I am not entirely familiar with what a VuMark is and am conflating it with the Navigation Targets. I did not partake in Relic Recovery. So I guess it's not surprising that there is no mention to these elsewhere but the existing resources have no deprecation notice as it is has not been relevant for a while.