Getting started as an OED code developer

The following steps should get you ready to contribute to OED in a fairly short period of time. Please know that we are here to help you so use the link at the bottom of the page to email us with any issues.

  1. First, we strongly encourage you to contact us as a potential developer. That way we know about you and can help you select tasks that will be interesting to you and also benefit the project.
  2. Before you can submit work to OED, you need to sign the Contributor's License Agreement.
  3. The OED project resides on GitHub so you need a login to contribute to the project.
  4. OED uses the fork model for development. (There are many descriptions of this process on the web but GitHub ones include a general one and one with more operational details.) This means you need to go to the main OED GitHub page (after login to GitHub), fork the project onto your own GitHub account and then clone the forked copy onto you own development machine to work on the code base. You can place the clone anywhere you want on your machine. Note the clone will place all the files inside a new directory named OED. This model has the advantage that you can commit and push to your account without needing write permission on the main OED project repository. There are separate directions of the steps for creating a pull request to integrate your code into OED.
  5. OED uses the Docker container system to run the software so you need to download and install Docker. (You need both Docker and docker-compose but you generally get those together during the install.) This has the advantage that our configuration files for Docker can get any needed software and also means we do not modify your normal system since the setup is in a separate container that does not impact other programs on your computer. Note that Docker should run on all OSes (Linux, Mac OS X, Windows - see below for information on using Docker with WSL on Windows) so you should be able to use it.
  6. You will want to install your forked/cloned copy of OED on your development machine. While there is further information on more advanced options for doing this, the initial install can be done by following these steps:
    1. Make sure you have Docker running on your system.
    2. If you are using WSL, you might need to follow these extra steps.
    3. Open a terminal on your computer (it is the "command prompt" on some Windows systems). In the terminal do the following:
      1. cd "directory with cloned OED"
        You need to replace "directory with cloned OED" with the location of the cloned copy of OED. This is where the "README.md" and other main OED files are located. Some people find it easiest to locate that directory using the file manager on their OS and then use that information to get to the needed directory. As an example, you might do
        cd /home/username/projects/OED
        if you cloned OED in the /home/username/projects/ directory.
      2. docker-compose up
        This will run the entire OED install process. Note that on some systems (mostly some Linux systems), depending on how you installed Docker, you may get a permission error so you will need to do:
        sudo docker-compose up
        which runs the process with root privileges. If this is the case then you need to do sudo before all docker commands on your system.
        Depending on the speed of your machine and internet connection, this can take a few to ten minutes. It should go faster after the first install if you follow the developer details elsewhere. You will see a lot of output about installing the database (Postgres), getting needed packages (this can take a while so you may not see output for a while) and starting up the web system. When you see the line:
        + 2073 hidden modules
        where the actual number will likely be different then OED should be running normally unless there was an error in the output.
      3. If you have any issues please copy all the output from your terminal and email it to us. We will look it over and get back to you. We try to do that quickly.
    4. Open a web browser. It should not matter which one you use. (Some developers prefer to work with Chrome when debugging code due to their debugging tools but other web browsers have good tools.) Enter the address:
      localhost:3000
      and load the page. "localhost" indicates the page is being served up from your machine and "3000" is the default port that OED uses to accept web connections. If all went well, you will see the main OED web page that looks something like:
      OED Main Page
      If you see that then the basic OED install worked and your system is properly serving up the OED web system.
    5. Though not common, it is possible for the OED web system to run without starting the underlying database system. To verify that the database is running properly, you should log into OED as the admin. The username and password were shown during the install process. By default they are:
      email: test@example.com
      password: password
      Yes, the password really is password but remember it is running on your local machine in a container so it should not be accessible to others. Test by clicking on the "Log in" button in the top, right corner of the main OED page. This will take you to the login page where you enter the admin credentials and click "Submit". If it works you will have another button in the top, right of the page for the "Admin Panel". If it fails you should see a message appear briefly in the top, right corner of the page. If this happens, please follow the steps above to email us the output in your terminal.
    6. If all went well, you now have a fully running development version of OED that can be used to begin coding. Congratulations!
  7. When you install OED, it does not have any data. An actual site would connect up meters to gather data. For a developer, we have standard test data you can use. The OED test data page has information and directions for doing this. We suggest you load up the data now so you can try any features you want in OED. Note that an advantage of this test data is that it is the same for all developers so people should be able to reproduce what you mention if you have a question or issue.
  8. You will want a coding environment to work on the OED code. We do not care what you use but note that many developers use Visual Studio Code that is freely available for all OSes.
  9. OED uses a number of technologies. You may want further information on these and some are provided on the OED technologies page. We welcome your input on other areas you would like to know about or other resources you find valuable. Note that you can work on parts of OED without knowing many of the technologies in any depth. For example, you can work on database queries without knowing about the front-end. Thus, many developers begin in areas they know or want to learn first and focus on that needed information. Having said that, almost the entire code base is in JavaScript/TypeScript so a basic understanding of that is usually needed to get started.
  10. There are two areas on our GitHub repo that are worth noting. First, the discussion board has several areas including one for developers. You are encouraged to subscribe to this discussion by clicking the button on the right side of the page with this discussion group. Second, the projects have an overview of the status of work and major initiatives.
  11. The What to Work on in OED page can help you figure out what to do.
  12. If you want help or have questions about running OED, then see the website or the help pages in the links at the top of the page.