Need newbie-friendly tutorials of the SDK Distro feature

Development
1

Following up from org.hibernate.HibernateException: Unable to locate named class org.openmrs.module.reporting.serializer.ReportingSerializer

This exchange was a great textbook example of @k_joseph asking a complicated question that requires some debugging in a specific environment, and @dkayiwa pushing him to document how to reproduce the error.

I think this would have worked even better if @k_joseph had known to define a Distro for the SDK, i.e. in a couple files he could specify OpenMRS core version, module versions, and SQL to run.

Basically, the Distro feature of the SDK is incredibly powerful and useful, but the documentation is too dense and opaque (there isn’t even a direct URL to the Distro section of the SDK docs) so most OpenMRS developers don’t realize how great it can be.

@adamg, @tmarzeion, @gutkowski, can one of you prioritize writing a step-by-step tutorial (I guess as a wiki page) giving a verbose and newbie-friendly description of how to build SDK Distros for various purposes? A few use cases that spring to mind are: (a) this example of having someone else replicate your environment to troubleshoot (b) setting up your first OpenMRS development environment to work on a ticket in openmrs-core © setting up your first OpenMRS refapp development environment to work on a ticket in a module (maybe it should replace this wiki page) © doing business-as-usual development of your own distribution, and using SDK commands to deploy module versions, etc.

Some examples to follow of what this might look like are step by step tutorials I wrote for UI Framework and App Framework, and of course you can find plentiful tutorials on the web for other things. :slight_smile:

(FYI @raff)

4 Likes
2

I would like to offer my services as a reviewer

2 Likes
3

@darius I think it is great idea, I believe @raff will like it as well, we will do it.

By the way, I think tutorial should cover (a) and (d), but (b) and © should be another wiki page about setting dev environment. And there is no point to separate module/refapp module/core development tutorials, because with SDK steps are essentially the same.

@ssmusoke thanks!

4

First draft: https://wiki.openmrs.org/display/docs/OpenMRS+SDK+Step+By+Step+Tutorials, covers setting up dev environment, creating basic distribution and replicating environment for debugging.

4 Likes
5

@gutkowski Just added “Why use SDK” section at the top

1 Like
6

Thanks for doing this @gutkowski! Your turnaround is much faster than my ability to review. :slight_smile:

Reading through this, I think you’re focusing too much of how, instead of why. Focusing on the Setting Up Dev Environment section:

  • I would title the section “Using the SDK to Contribute to an existing OpenMRS module”
  • Describe the scenario why someone might want to contribute to a module (e.g. they are working on a ticket and they want to add a feature)
  • Give the big picture of what they need to do: set up a server, check out the module code, make changes (with TDD!), deploy them to the server, and run it

Does this make sense?

7

@darius thank you for feedback! Probably you are right, that we should include more ‘big picture’. I will introduce the changes you requested in the coming days :slight_smile:

8

I think this thread got dropped, but it would be really good to have a better tutorial that we can point people to.

(Bump.)

9

@tmarzeion @adamg @gutkowski @raff any response to this? :slight_smile:

10

@gutkowski did some work on that here https://wiki.openmrs.org/display/docs/OpenMRS+SDK+Step+By+Step+Tutorials

I heard in the past there are many volunteers interested in working on documentation. Maybe we could get their help here as every feature is pretty much documented and we just lack proper structure and flow.

11

@raff at the moment, we do not seem to have volunteers for this task. What do you suggest as the way forward regading these SDK newbie tutorials? :slight_smile:

12

There’s value in having tutorials/screencasts done by someone who isn’t on the dev team of the SDK, i.e. someone who won’t be tempted to go deep into the weeds of the SDK, but instead just show how to use it at a high level for common tasks.

Is there someone who’s interested in improving the onboarding experience who might want to do this? @dkayiwa, @teleivo?

13

I can help putting together a tutorial based on the most common workflows that I use - probably early next week as I am currently swamped putting together a release this week. This can provide a foundation for adding more work flows

2 Likes
14

@samuel34 do you think you can also be of help in regards to this?

15

let me try it out en see

16

@dkayiwa I think I will need your help in this . coz am realizing that I gat a poor insight in documentation
 And tell me the tools needed coz am having only eclipse installed on my PC


17

First of all, have you read the entire conversation on this thread? Including the given links?

18

@dkayiwa I have tried to read everything followed all links but am failing to understand
 can give me a hint please??

19

@samuel34 first step would be for you to try out the openmrs sdk https://wiki.openmrs.org/display/docs/OpenMRS+SDK

20

man am still on the Newbie case but my first confusion is in the UI FRAMEWORK STEP BY STEP TUTORIALS
 where by this guy was using some other programming language
 which I don’t understand but thats no big deal
 Next> in that UI FRAMEWORK STEP BY STEP TUTORIAL, that guy was demostrating how one creates a page but my greatest bottle neck is with the mix up of differ languages java and some other language!! Is that the way we you guys do things OR??? And my other great interest is with creating a module, man am having a poor insight on that
 but I wana get started on it
 PLEASE HELP ME OUT!!!