This documentation contains a set of guidelines to help new users and potential contributors to MDF.
Before opening pull requests, make sure that you read these guidelines. If you have any doubt on this contributing guide, please feel free to reach out on our discussion forum.
-
Install the MDF package and all its dependencies: https://github.com/ModECI/MDF (see here for full details).
-
Try running locally the standard MDF examples: https://github.com/ModECI/MDF/tree/main/examples/MDF
-
Run the following notebook, altering the network elements along the way to build your own model: https://github.com/ModECI/MDF/blob/main/examples/SimpleExample.ipynb.
-
Read the documentation on the elements of the MDF specification: https://mdf.readthedocs.io
-
The project uses an issue tracker to keep information about bugs to fix, project features to implement, documentation to write, and more. Potential contributors can look for newcomer-friendly issues by looking for the following issue tags in the project issue tracker:
good first issue.
Following are the steps to guide you to making your own fork of the MDF repository, making changes and submitting them as contributions:
Create and activate a virtual environment for MDF as outlined in the main installation guide.
Fork the MDF repository on the GitHub website, and then go to your terminal and clone it on your machine.
git clone https://github.com/<your_fork_name>/MDF
Add an upstream link to main branch in your cloned repo.
git remote add upstream https://github.com/ModECI/MDF.git
Keep your cloned repo up to date by pulling from upstream (this will also avoid any merge conflicts while committing new changes)
git pull upstream main https://github.com/ModECI/MDF.git
Create your feature branch. Note: it is useful to give this a name relevant to the issue being addressed e.g. feat/my_new_feature or bugfix/123 (to fix issue #123)
git checkout -b <feature-name>
Make your changes! Run the tests in test_all.sh to make sure all tests are passing locally.
Format your code. We use a standard format (black) for all our code, as this minimises the changes between commits especially when people have different coding styles. Install pre-commit using pip install pre-commit and type pre-commit run --all-files at the top level MDF directory to format the code. This will change all the relevant files to the correct formatting before you commit. This formatting is checked by our GitHub Actions tests and will fail if the code is not correctly formatted.
Commit your the changes. Note: if you have run the test_all.sh, many of the image files will have been regenerated (and may show as changed even though they are identical). Don't commit these unless you know there is an actual change.
git commit -m "A meaningful, concise commit message"
Push the changes to your fork
git push origin <branch-name>
Create a PR on GitHub.
- Don't just hit the create a pull request button, you should write a detailed PR message to clarify why and what are you contributing.
- Put the hashtag of a relevant issue in a commit message for the pull request (e.g. #123), and it will show up in the issue itself which will make easy for developers to review your PR based on the issue.
- Markdown : Markdown is a lightweight markup language like HTML, with plain text formatting syntax.
- Git : Git is a distributed version-control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files.
You can refer to the following articles on basics of Git and Github, in case you are stuck: