Journal of looking at OpenLMIS as an external dev

I spent a couple hours with the idea that “I want to build the code, as a dev unfamiliar with the project so far.” It was not as straightforward as it should be. Here’s my journal, with specific recommendations called out:

From openlmis.org on the “Participate” links there’s no way to get to the code. The only I can find to get to github from the website is via Learn, which is not intuitive. Also, this lands at https://github.com/OpenLMIS/open-lmis which shows the last activity 4 months ago.

  • we need to funnel people who might be interested in getting on board to the right place
  • need to send people to where active development is happening, or we look dead

Going to the wiki, and clicking on “developer guide” I cannot find the how I would set up a dev environment for 3.0 work. (It’s fine in this is primarily documented on github but if so we need to link to it from the wiki.)

Also, nothing about the active work is highlighted (e.g. the Architecture Overview page or something about ongoing sprints)

  • it should be easy for an interested dev to figure out how to start
  • it should be obvious what the main thing going on is for OpenLMIS community

Eventually I found https://github.com/OpenLMIS/openlmis-blue.

First problem is that there’s no “env” file, and I can’t find any instructions on the wiki about this. Also, openlmis-blue’s README doesn’t say how to do anything.

  • the README should always have up-to-date instructions for how to run things (and we should be sticklers about this)

Searching the mailing list I found this, which points me to a file that maybe works. When doing “docker-compose up” I eventually hit “ERROR: Tag latest not found in repository docker.io/openlmis/requisition

  • This should work, or our instructions should point to something else that works.

So, via the wiki I made it over to Jenkins at http://ci.openlmis.org:8080/ to see if the latest build of requisitions is green. I see that “OpenLMIS-requisition-service-strict” is broken (and has never built successfully) I assume this isn’t the build I’m looking for, and “OpenLMIS-requisition-service” is what I really want.

  • Any CI builds that are not consistently green should be disabled/removed, or something like that. (We shouldn’t be in the habit of having some red builds that we know are okay if they’re broken. An observer with no special knowledge should be able to look at our CI and see if everything is good or not.)

Now, I know that requisitions is the most recently worked on thing (from github history), so I checked that out. It has a much better README. (Though, when there are actually multiple independent services we should have the bulk of the documentation somewhere shared, such that anyone who has read this basically knows how to build/develop a convention-following service.)

Requisitions runs fine (Woohoo!) though the promised “user-friendly and interactive version of the API spec” doesn’t materialize. (Here’s a PR to remove that from the readme, if it’s not just my problem.)

  • It would be nice to have some kind of demo/test data (low priority, I imagine)
  • Or at least a one-line suggestion in the readme about the first command one might consider running after starting things up
···

Darius JazayeriPrincipal Architect - Global Health
Email
djazayeri@thoughtworks.com

Telephone
+1 617 383 9369

ThoughtWorks

I would agree that the current solution we have with the .env file is not ideal - would it make sense to assume some defaults on our end and make it runnable without having the .env file for changing the config? If we are aiming to improve new developer experience that’s something we could do.

  The link for the Swagger documentation was corrected, from what I understand it was missing an /index.html part. Do we want to change that url to something like /swagger down the line?

Regards,

Paweł

···

On 20.07.2016 02:30, Darius Jazayeri wrote:

      I spent a couple hours with the idea that "I want to build the code, as a dev unfamiliar with the project so far." It was not as straightforward as it should be. Here's my journal, with specific recommendations called out:

From openlmis.org
on the “Participate” links there’s no way to get to the code. The only I can find to get to github from the website is via Learn, which is not intuitive. Also, this lands at https://github.com/OpenLMIS/open-lmis
which shows the last activity 4 months ago.

  •           we need to funnel people who might be interested in getting on board to the right place
    
  •           need to send people to where active development is happening, or we look dead
    
      Going to the wiki, and clicking on "developer guide" I cannot find the how I would set up a dev environment for 3.0 work. (It's fine in this is primarily documented on github but if so we need to link to it from the wiki.)
      Also, nothing about the active work is highlighted (e.g. the [            Architecture Overview](https://openlmis.atlassian.net/wiki/x/IYAKAw) page or something about ongoing sprints)
  •           it should be easy for an interested dev to figure out how to start
    
  •           it should be obvious what the main thing going on is for OpenLMIS community
    

Eventually I found https://github.com/OpenLMIS/openlmis-blue.

        First problem is that there's no "env" file, and I can't find any instructions on the wiki about this. Also, openlmis-blue's README doesn't say how to do anything.
  •             the README should always have up-to-date instructions for how to run things (and we should be sticklers about this)
    

Searching the mailing list I found this , which points me to a file that maybe works. When doing “docker-compose up” I eventually hit “ERROR: Tag latest not found in repository docker.io/openlmis/requisition

  •             This should work, or our instructions should point to something else that works.
    

So, via the wiki I made it over to Jenkins at http://ci.openlmis.org:8080/
to see if the latest build of requisitions is green. I see that “OpenLMIS-requisition-service-strict” is broken (and has never built successfully) I assume this isn’t the build I’m looking for, and “OpenLMIS-requisition-service” is what I really want.

  •             Any CI builds that are not consistently green should be disabled/removed, or something like that. (We shouldn't be in the habit of having some red builds that we know are okay if they're broken. An observer with no special knowledge should be able to look at our CI and see if everything is good or not.)
    
          Now, I know that requisitions is the most recently worked on thing (from github history), so I checked that out. It has a much better README. (Though, when there are actually multiple independent services we should have the bulk of the documentation somewhere shared, such that anyone who has read this basically knows how to build/develop a convention-following service.)
        Requisitions runs fine (Woohoo!) though the promised "user-friendly and interactive version of the API spec" doesn't materialize. (Here's [              a PR](https://github.com/OpenLMIS/openlmis-requisition/pull/12) to remove that from the readme, if it's not just my problem.)
  •             It would be nice to have some kind of demo/test data (low priority, I imagine)
    
  •             Or at least a one-line suggestion in the readme about the first command one might consider running after starting things up
    

Darius Jazayeri* Principal Architect - Global Health*
Email
djazayeri@thoughtworks.com

Telephone
+1 617 383 9369

ThoughtWorks

  You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.

  To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.

  To post to this group, send email to openlmis-dev@googlegroups.com.

  To view this discussion on the web visit [https://groups.google.com/d/msgid/openlmis-dev/CAOKb-R4mynyPM_RFhqkHiTF8ACCZ0kBJLwkrdx7yyBq1hujvJA%40mail.gmail.com](https://groups.google.com/d/msgid/openlmis-dev/CAOKb-R4mynyPM_RFhqkHiTF8ACCZ0kBJLwkrdx7yyBq1hujvJA%40mail.gmail.com?utm_medium=email&utm_source=footer).

  For more options, visit [https://groups.google.com/d/optout](https://groups.google.com/d/optout).