A quick overview guide of the Devstack

Hey, all!

One of the most common frustrations we’ve found when onboarding new devs at OpenCraft is a general sense of feeling ‘lost’ when encountering the devstack for the first time. While there’s no substitute for working with it for an extended period, we felt it would be helpful to write up a little guide article that walks through the structure of the devstack and common commands that new devs may find useful. We thought those in the community would like to know about it.

The article is available here and I’d love to hear your feedback on it. :slight_smile:





The article looks good! I’m currently onboarding some new devs and I’ll send it over to them.

One thing that could be useful to mention installing themes in the edx-themes folder in the Devstack workspace.

Thanks! I’ve not installed a theme using that method (I don’t think). How would you go about it? Do you clone a theme repo in the edx-themes directory and then update some settings? Which ones? Have an example theme repo I can clone to give it a try?

Or maybe I should just mention that you can do it and point to a more in depth part of the docs? Theming seems used less often but it’s good to know it’s there.

I have some instructions here, feel free to take from it.

I agree, it doesn’t need to go into many details.

@Fox_Piacenti Thanks for the blog post!

Btw, since there is currently work being done to create/improve a shared onboarding course for new Open edX developers, maybe this could be incorporated there? @omar @nimisha What do you think?

OK. I’ve updated the post with a little note about it and a link to yours.

@antoviaque You’re welcome-- and that sounds great to me. I’m curious what @omar and @nimisha would think, too!

@Fox_Piacenti Thanks for taking the time to write this up!

In terms of location of this content, I’m wondering whether we can merge it with the README and docs that are already in the devstack repo.

One of the principles we called out in our Developer Docs Requirements, is “co-location” of docs with its relevant code. The assumption is that co-location will enable long-term maintenance of the doc. Otherwise, the code and the doc will get out of sync.

I’d also add that duplicative reference information can be confusing for developers - especially when they onboard. Note that both the blogpost and the devstack README have a “Getting Started” section.

So I’m wondering if there’s an opportunity to use the work you have done and merge it with the Devstack docs. Maybe with the README and the /docs folder? Or you may have better ideas.

I’ve been mulling over this. The problem of the devstack, as I see it, is that a lot of the most important information/pertinent information to new developers is scattered. The README at current does give good setup instructions, and covers a handful of commands, but not as many as I’d expect a new developer to need.

My feeling is that perhaps we should be removing almost all of the contents of the README and pointing to the readthedocs build instead, and that this should contain the getting started section, perhaps with a quick reference in the manner I’ve made with the blog post. In fact, I missed the link entirely because my eyes skimmed down and saw documentation I could immediately use. I was not even aware there was further documentation for the devstack than the README.

Does this seem sensible? I think we could look into better consolidating the docs that way.