Developing ixdat
If there’s an experimental technique or analysis procedure or database that ixdat should support and doesn’t, it might be because you haven’t coded it yet.
Here are a few resources to help you get started developing ixdat.
Git and Github
The source code for ixdat (and this documentation) lives at: https://github.com/ixdat/ixdat
To develop ixdat, you will need to use git and github. This means
install git. Git bash works well for Windows.
Create an account at https://github.com
Make a fork of https://github.com/ixdat/ixdat so that you have your own version of the ixdat repository on your own github account.
Clone your repository. Navigate in the terminal which you will use for git (e.g. git bash) to the location that you want the repository (e.g.
/c/Users/your_user_name/git/
), and type:git clone https://github.com/ixdat/ixdat
Install ixdat from the repository to use the ixdat code you’re working on. You can do this in a virtual environment, but it is simpler to just install it dynamically. In your terminal or Anaconda Prompt, navigate to the folder which contains the ixdat project folder (e.g.
/c/Users/your_user_name/git/
) and type:pip uninstall ixdat pip install -e ixdat
If you want to go back to using the released version later, just re-install it from PyPi:
pip install --upgrade ixdat
Switch to the branch you want to work from. Note, this is also how to use a feature that is under development.:
git switch branch_to_work_from
Usually it makes most sense to start work by branching from the main branch:
git switch main
Make and switch to a branch on which to develop your feature:
git switch -c my_feature_branch_name
Develop your feature, committing regularly and pushing regularly to your github account.
When it’s ready (i.e., works like you want, and passes linting and testing), make a pull request! A pull request (PR) is an awesome open review process that gives others a chance to comment and suggest improvements in your code before it’s merged into the main ixdat package. You can see existing pull requests at https://github.com/ixdat/ixdat/pulls
NEXT_CHANGES.rst
When you contribute to ixdat, add descriptions of your changes to the file NEXT_CHANGES.rst in the main project folder. This makes it easy for us to keep track of everything that will be included in the next release of ixdat. When you make a pull request, we will remind you to update NEXT_CHANGES.rst if you haven’t done so.
When we release a version of ixdat, we do the following:
Increment the version number according to the semantic versioning conventions
Copy-paste your descriptions and others from NEXT_CHANGES.rst to the main changelog, CHANGES.rst
Build ixdat using setup.py
Upload a copy to PyPI so that the new version installs with
pip
style
We do our best to follow the conventions at
code style guide: https://www.python.org/dev/peps/pep-0008/
docstring style guide: https://www.python.org/dev/peps/pep-0257/
Exceptions include
It’s fine to capitalize names for a quantity that is conventionally capitalized in equations (T for temperature, for example).
The tools black and flake8 help us keep the style up to standards.
tools
We use tools to make sure that our code is both functional and pretty. This makes it easier to work together. See instructions for the tools in tools.rst
Testing
Software tests are welcomed! The basic test suite is included in this
repository in the tests
directory.
However, if your tests have a specific purpose and/or depend on additional
data, then the data should be initialized in a submodule. Additionally,
the tests should be marked as external
with the pytest mark decorator.
It is done like this, so other developers do not have to download your data
through submodules, when they do not wish to test their new feature with your
tests and data.
If you want to run the complete test suite that includes external tests from all contributing developers, you need to initialize necessary submodules:
git submodule update --init --recursive
In order to download a specific submodule (e.g. ixdat-large-test-files
), the command is:
git submodule update --init submodules/ixdat-large-test-files
And then run command for testing with --external
option:
# the 'tests' here is an invoke command
invoke tests --external
# or just with pytest, if you wish:
# the 'tests' here is a project directory with the tests
pytest tests --external
Tutorials
The tutorials for ixdat is developed in a separate repository. But these tutorials are copied into the ixdat repository in order to be able to generate docs from the Jupyter notebooks for the documentation: https://ixdat.readthedocs.io/
We are trying to figure out the best way to automate this process (see https://github.com/ixdat/ixdat/pull/133), but for now just copy the updated files of the tutorials repository into the corresponding place in docs/source/tutorials/tutorials_repo an compile them manually.
All files in docs/source/tutorials/tutorials_repo are ignored by the ixdat repo’s .gitignore except for the .ipynb files.
The tutorials should be reviewed and merged on the tutorials repo (in un-compiled state) before being added to the tutorials page of the documentation.
Write to us
We’d love to know what you’re working on and help with any issues developing, even before you make a PR. One great way to do so is through github discussions