potiuk commented on issue #19566: URL: https://github.com/apache/airflow/issues/19566#issuecomment-968104545
Hello @karakanb - thanks for that very detailed description. There are probably about 10 issues specified in this one entry, so it's next to impossible to do any reasonable action with it. However let me try and have a proposal: Airflow has >1800 contributors and many areas (the guides including) are created by many of them. We continuously improve it and actually the best way to contribution works is to turn experience of first time contributors into correcting the docs, removing silent assumptions that more experienced people have. You seem to know well already how to improve the documentation for first time contributors, and since you are one, you probably have - correctly assessed what is confusing for you, so this is a great chance that you can correct it best by submitting PRs fixing some of those issues. We do not require (and even discourage) people from creating issues for such (non-core, mostly documentation changes). You are completely free to start PRs directly proposing fixes to some of those changes you mentioned (but please, one "area" to fix in one PR - the more you split the easier it will be to review, get comments from others and approvals from committers to merge them. Answering some of your questions: * First of all you can see the recording from the first-time-contributors workshop we run in Mexico OCSS conference earlier this year https://youtu.be/kvccZizzfTk - it migh give you some more context on why we need more than one env (local + breeze) and might help to make your PRs better. * one thing you have to remember is that not everyone is like you. There are people who have no Docker experience whatsoever and their programming is done mostly in the IDEs. The path you proposed is good for someone who knows vi or nano and is comfortable with using them, but MANY people (especially those who use Windows as their primary development platform) just use IDEs to do EVERYTHING. I would not dismiss such people - they are those who needs most help actually to get familiar with our environment. But maybe indeed a good idea (PR please?) to mention both possibilities in the docs and structure it in the way that people who have this experience will do it this way and people with IDE-only approach will do it differently. You have to always remember that you do not know who the reader is and you should assume that 90% of people reading it will have different background, experience, skills than you and you need to produce something that is good for all those people. * yeah you need both - local virtualenv and dockerized Breeze environment in various circumstances. Breeze gives you "consistent" environment that is the same for everyone and avoids "works for me" kind of problems, where local virtualenv integrates better with IDEs and is generally much faster on MacOS, WSL2 environments (which VAST majority of our users use). You already saw that with yarn, but there are other cases where local virtualenv is better. A lot of details about it described in the main "CONTRIBUTING.rst" https://github.com/apache/airflow/blob/main/CONTRIBUTING.rst#development-environments - where comparision between the two is explained. What is likely a good candidate for PR (another one!) is to find a way to explain it in "quick quide" in the way that is not overwhelming and without the assumptions others have. The `jq` is needed for some parts of breeze. I am not sure if it makes sense more than "it's needed". It is needed to run "kind/kubernetes" tests which are also run using breeze scripts and to test production images. I am not sure if the new user is even able to assess if they will need it or not initially, so better to just say "you need it" . But if you will have a proposal how to put in the way that will not add more confusion, I am all ears and happy to get (another) PR with that. Eventually, what i really would love is a series of PRs proposing fixes to those problems you raised. All the community is very open and greatful for new contributors to improve our docs and developer experience and you seem to be the best kind of person to do it: * you already know what annoys you * you seem to know how to fix some of that * you do not have all the assumptions more Airflow-dev-experienced people have * this something that we keep on repeating on our workshops - improving the contributions docs is one of the BEST contributions you can do as first-time contributor. It is. You can pay back for the software you get for free AND help others like you! So you seem ideal person to do it ! I hope I armed you with enough knowledge above - and even the recording from the workshops, so that you can get the missing context and propose it in the way that will be best for people like you. Now -finaly (since I went through the ~10 issues you raised additionally in this one comment). Regarding assets generation: You just need to do it once (following the warning you correctly followed) - what @kaxil mentioned is true - but this is not MacOS only. You NEED to generate the assets once because they are not automatically generated at first entry (I wanted to do it but that would slow-down the experience of people who do not care about webui and running - quite many of them) . However when you run `start-airflow` command it **SHOULD** be exceuting automatically, so the warning should not be there. Unless there is an error in som of the "entrypoint" scripts, it is rather likely something specific to your environment. I wonder if you could prepare a gist with detailed dump of the logs you see when you run `start-airflow' - from each of the tmux terminals. That will make it possible to take a look of what you are experiencing and maybe we will be able to find out what's th e reason and fix /improve it. Once you compile the assets once in your sources, they should remain there. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
