Glad to hear the readme was useful! I lean towards keeping it in GitHub, but agree there should be more cross linking with the Wiki.
Reason being is that README content shows up in the Go Package Doc site: eg. https://pkg.go.dev/github.com/apache/beam/sdks/v2/go Granted we don't make 100% the best use of this at present. On Tue, Feb 8, 2022, 2:23 PM Danny McCormick <dannymccorm...@google.com> wrote: > Thanks! > > > I'm curious if you found this lengthy contributing guide daunting, > especially for non-java development. (I know I would.) > > To be honest, that wasn't a huge issue for me - I think there's certainly > room for making it better, but I actually appreciated the level of detail, > and didn't really have much of an issue getting going with development once > I found the guide. Some of that is almost certainly related to my > background - I have a bunch of experience ramping up in unfamiliar repos > from my time with GitHub (internal and external repos) and am probably > undeterred by longer guides as a result (a longer guide actually is often a > plus in my mind). I can definitely imagine that being a blocker to someone > who has less experience ramping up on open source repos. > > You didn't really ask for this, but if I were to try to give more focused > feedback on the guide (and related resources) specifically, I'd say: > > 1. The `local-env-setup.sh` script worked perfectly and was a big boost - > continuing to maintain that well will make getting started a lot easier for > new contributors. > 2. It took me a long time to find the docs that are in the confluence > wiki. From https://beam.apache.org/contribute/ you kinda just need to > know that the side panel links to that and that there are a lot more docs > available there than are rendering in that side panel (e.g. Go Tips with > instructions on building/testing would have been really helpful, but I had > no clue it existed for a bit - the same goes for Java/Python tips I think). > I think our cross linking could be better on that initial landing page to > expose more of those confluence docs (or at least the relevant ones). > 3. The instructions on joining the slack channel didn't work for me here - > https://beam.apache.org/community/contact-us/ > 4. The Go Sdk has some (pretty helpful) instructions in its root readme - > https://github.com/apache/beam/tree/master/sdks/go - Java and Python > don't. I lean towards moving the Go docs into the wiki and leaving behind a > link, but if not we probably need to do something to make that more > discoverable. > > Again though, I generally found the guide helpful if imperfect and the > hard pieces were not central to getting started (except maybe the > confluence discoverability bit). > > Thanks, > Danny > > > On Tue, Feb 8, 2022 at 4:56 PM Robert Bradshaw <rober...@google.com> > wrote: > >> Thanks for contributing, and welcome! >> >> Good feedback. One question inline below. >> >> On Mon, Jan 31, 2022 at 12:17 PM Danny McCormick >> <dannymccorm...@google.com> wrote: >> > >> > 👋 Hey folks, my name is Danny - I recently completed my first Beam >> PR[1] (a small extension to the Go Dataflow runner) and am planning on >> becoming a more regular part of the community. As such, I wanted to use my >> fresh newbie eyes and share some of what was nice and where there was >> friction about getting started. >> > >> > Disclaimer: this is coming from the perspective of someone who is >> pretty used to open source development, but has minimal experience with the >> Apache way, Beam, and the languages my change came in. I'm hoping my >> experience is helpful to those of you who have been around for a while and >> haven't seen things as a newcomer in a long time, but it may not be >> reflective of the experience of others. >> > >> > Things that were really nice: >> > >> > - The community has been really welcoming and encouraging of >> contributions, something I saw in my first code review, my first pr, and >> even the tone of the docs. Special thanks to @lostluck and @jrmccluskey for >> making my first interactions welcoming and prompt. That experience can be >> the difference between one time and repeat contributors. >> > >> > - Getting started writing my first pipeline, and then ramping up to >> more complex concepts was surprisingly easy - in particular, the docs, >> examples, and Katas made for a reasonably smooth process. It wasn't always >> clear how to go from that to more complex transforms and there's of course >> room for more clarity, but I appreciate the work that's gone into the >> getting started experience. >> > >> > - Overall, the code base is pretty easily understood/reasoned about, >> and the high quality of code made it pretty easy to make my first change. >> I'm pretty impressed at how simple/well composed this system is even as it >> approaches a tricky problem space (hopefully I'm saying the same thing >> after I make some bigger changes :)) >> > >> > Friction Points: >> > >> > - It was harder than expected for me to figure out what made Beam >> different/special from other tools in the space out there for users. >> Specifically, it wasn't immediately obvious why I would use Beam instead of >> just running my jobs directly on Spark or Flink or one of the other >> runners. One pretty big challenge here was that I didn't really get how >> easy it was to switch runner types/how powerful the portability (and >> unified streaming/batch) model was. I'm not sure exactly what would make >> this easier for someone new to the space, but some sort of graphic or brief >> statement of "this is where Beam adds value over most other frameworks" in >> the Readme would be cool. >> > >> > - There were some small paper cut usability things in the repo. >> Specifically, it looks like the labeler is broken (issue[2] and pr[3] added >> to address this) and there isn't a CONTRIBUTING.md (issue[4] and pr[5] >> added to address this), though the contribution guide is linked elsewhere. >> Both of these are probably non-issues for experienced contributors, but add >> a small amount of friction for people who are trying to get involved, >> especially those who navigate a fair amount of OSS repos, and they're >> pretty easy to fix. >> >> I'm curious if you found this lengthy contributing guide daunting, >> especially for non-java development. (I know I would.) >> >> > - I know there's some separate discussion about this in a different >> thread[6], but the use of Jira instead of GitHub issues added a layer of >> friction to getting started. Concretely, I would've put up my first pull >> request and created my first issue earlier if I didn't need to go through >> the process of creating a Jira account and getting permissions to assign >> tickets, and it was harder to find a good first issue to contribute to. I >> can imagine others might not have pushed through that. >> > >> > With all that said, I'm really excited to be joining the community and >> get to add to Beam, and I hope it was helpful or interesting to get a >> newbies perspective. >> > >> > [1] https://github.com/apache/beam/pull/16643 >> > [2] https://issues.apache.org/jira/browse/BEAM-13779 >> > [3] https://github.com/apache/beam/pull/16665 >> > [4] https://issues.apache.org/jira/browse/BEAM-13780 >> > [5] https://github.com/apache/beam/pull/16666 >> > [6] https://lists.apache.org/thread/q5nbwxqvfkzlz664c4kchzkbj26c3r89 >> > >> > Thanks, >> > Danny >> >
