OED Pull Request
While developing your code, we suggest you do the following:
- Create a branch of development branch (the main OED branch that is the default when you clone OED) and give
it a name that indicates the work you intend to do.
- Write test cases for your code. We use Mocha/Chai for testing and a description of it
location and use in OED is available. We need to have all code carefully tested to know it is
working when created but also stays working as future changes are made to OED. Writing good test code takes
real effort but it needs to be done.
- Make sure you run OED in a web browser and it works as expected. Please check any feature that might have
been impacted by your work and do a quick general check of the system so you know it works.
- Consider if your changes impacted code or documentation that needs updating. For example, did your code
change OED usage so the help pages needed updating? Did you add a script so the Code Organization web page needs update? Did you change database usage or a
function used elsewhere in OED so other code update is needed? It is impossible to give a full list but
checking this out helps the
project. In some cases you can note the needed changes in your pull request to make sure they get done
outside your work.
- Run our checks. Lint is a system that verifies that your code does not have certain syntax or running
issues along with making sure it follows our expectations for code style. It also verifies that each file
has the needed license at the top and that TypeScript is used where expected. You will likely find it easier
you run this check early to find any issues so you don't repeat them many times. The checks are run in a
terminal. The safest way is to do it inside Docker (by using docker-compose). To
do this do (from the main OED directory as needed for all docker-compose commands):
docker-compose run --rm web npm run check
You can run the check outside of Docker with:
npm run check
where you need to have npm
installed on your system outside the Docker OED system. Note that the checks use certain Unix commands that
may not run or may not run as expected on your system so even though this is faster we recommend doing it
inside of Docker. Note that unlike doing an install, you do not include --service-ports since it is not
needed and allows you to run this even while the instance of OED is active. If you get a permission error
when running the checks inside docker then check out this issue.
- Run our code checks. These run all the test cases to verify the code is running correctly. It is similar to
running lint where you use:
docker-compose run --rm web npm run test
This can take several minutes. A summary will be given at the bottom. If you see any errors then they should
be checked out. Let us know if you need help. You will do the same command to check any new tests you add.
Please note that it is difficult to run the tests outside Docker (with the full OED install) so you should
not do that (unlike using it with the lint check). See other info
for faster running of single tests for debugging. Also note that the tests deliberately try to do invalid
operations to test OED. This causes warning/errors in the log.txt file as well as in the PostgreSQL log that
will be shown in the next install. Finally, note that unlike doing an install, you do not include
--service-ports since it is not
needed and allows you to run this even while the instance of OED is active.
- Make sure you keep your fork up to date with development on the main OED GitHub. Other people may integrate
new code into OED and your work needs to be in sync with that work.
When your fork has code that is ready to add to the OED code base, create a pull request from your branch into
development on the main OED GitHub repository (GitHub
documentation). The pull request template should include the following:
- An area at the top to describe this PR. It states: "Please include a summary of the change and which issue
is touched on. Please also include relevant motivation and context."
- Note any issues this PR addresses. Check to see if
you are addressing any open issues. If so, please note in the pull request description. If your pull request
completely fixes/addresses an open issue then put the words "Fixes #XXX", where XXX is the issue number. If
it only partly addresses an issue then use "Partly Addresses #XXX".
If it fixes an open issue then everyone will see the a note in the pull request (after opened) indicating it
will close this issue when
merged and there is
also a related note in the issue.
- There is a checkbox to indicate: "Note merging this changes the node modules." This indicates you changed
package.json so that new packages
or versions are needed. This indicates to others that is it not safe to use the "--keep_node_modules" option
when installing OED.
- There is a checkbox to indicate: "Note merging this changes the database configuration." This indicates that
the database needs to be updated
for these changes to work correctly. Normally there will be migration files to update the database. However,
many developers will choose to reinitialize the database to do a clean install to be sure everything works
- There is a checkbox to indicate: "I have followed the [OED pull
- There is a checkbox to indicate: "I have removed text in ( ) from the issue request"
- An area to list any limitations of the PR: "Describe any issues that remain or work that should still be
- If your work is not yet ready and you are sharing to get early feedback, please make the PR as a draft.
When your pull request is submitted, automated GitHub Actions will run including static code checks and the OED
test code that will
do the checks and tests. If they pass then a green check mark will be put next to them and your pull request can
be considered. If they fail, you should see why and fix the issue on your branch. When you push the change to
your GitHub account (with the fork of OED), your pull request will automatically be updated and recheck.
You can tell if there were any issues with the automated GitHub Actions by looking at the commit on the pull
request. Toward the right side of the line with the commit there will either be a green check mark (everything
okay) or a red x (indicating issues). (It could be yellow of the checks have not finished which normally takes
1-4 minutes.) If you click on either, a popup has a link to the "details". Normally the
issue is with the OED tests (and not from the automated testing setup). To see these, open up the section
labeled "node tests". This will show all the checks (lint, typescript, etc.) and the automated unit tests.
Normally there will be an error message (either at the end or in several places). This should indicate where the
error occurred and help in tracking it down. Note that an error can cause the testing to stop so it is possible
there are more errors that will show up once the earlier one is fixed. See above about running the tests on your
machine and the developer
details page has information on running a limited number of tests.
Once your pull request is passing all automated checks, it needs to be reviewed by at least one OED team
member with that privilege. The review might make suggestions and may request changes. Once that process is
complete, a senior member of the team will either approve the pull request of make other comments. Once
approved, the pull request can be merged into development for inclusion into the OED code base.
As always, if you have questions about this process or run into issues, you can contact the development team
using the link at the bottom of this page.