Welcome, and thanks for considering Metatheory.jl! Please be sure to respect our community standards in all interactions.
We gratefully acknowledge the general Julia CONTRIBUTING.md document, from which much of this was adapted.
A pre-requisite for using Metatheory.jl is to know at least a little about Julia itself. The learning page has a great list of resources for new and experienced users alike. This tutorial video is one recommended starting point, as is the "Invitation to Julia" workshop video from JuliaCon 2015 (slide materials here). The Julia documentation covers the language and core library features, and is searchable.
Our main documentation provides an overview and some examples of using Metatheory.jl. The core package is hosted at Metatheory.jl.
Julia's own "How to file a bug report" has many useful tips to help make sure that all necessary information is included.
Try to report the issue in the package responsible for the error.
You can often make good guesses by examining the backtrace (in cases where an
error is thrown), using @which, stepping in with the debugger, or just
using the search bar at the top left of Metatheory.jl.
By contributing you agree to be bound by Metatheory.jl' MIT license
Many documentation issues are easy! For small changes, you can just click on one of the files in the docs/src directory, click on the "pencil icon," and edit it in your browser. Any changes you suggest will first be vetted by an experienced developer, so there is no need to worry that you'll mess something up.
Changes to the "docstrings" (the string preceding a method in source code) should be made in the package in which they appear.
For bigger documentation changes, it is probably best to clone the package and submit the changes as an ordinary pull request, as described below under "Contributing code." You can build the package locally if you install Documenter.jl, and run include("make.jl") in the docs/ folder. To see the completed documentation, open the build/index.md file in your browser.
By contributing you agree to be bound by Metatheory.jl' MIT license
If you've never submitted a pull request before, it can take a little while to become familiar with the process. In addition to the steps below, GitHub has a tutorial and exercises. See also the excellent Git book. There are also many good external tutorials on this subject, like this one.
-
Create a GitHub account.
-
If you plan to fix a bug, feel free to first report the bug as an issue on its own. In the text, you can mention whether you're planning on addressing it yourself. Pro tip: if you do submit a pull request to fix it, put "Fixes #" in the commit message and it will close automatically when your pull request is merged.
If you're concerned your change might be controversial, you can also use an issue to propose your change in general terms and discuss it before implementation.
-
Fork whatever repository you plan to commit to by clicking on the "Fork" button at the upper-right of the home page.
-
If you haven't already implemented your changes, check the package out for development: hit
]in the Julia REPL and then type (for example)dev Images. You'll get a copy of the full repository in your~/.julia/devfolder. See the package manager documentation for further details. -
Make your changes. Generally you should be working on a branch, so your work doesn't conflict with ongoing development in the
masterbranch. Ensure you follow the Julia style guide for your contribution. -
Test your changes. We aspire to have test coverage for every bit of "user visible" functionality. Tests are stored, appropriately, in the
test/folder of each package. You can run existing tests yourself and add new ones. Sometimes testing is more work than the actual change itself, but having tests ensures that no well-meaning future developer will accidentally mess up your functionality---it's worth it! "A fix is for today. A test is forever." -
Submit your changes up to your fork and then submit a pull request-!
-
See what happens to the automated tests that run on Github Actions. If there are errors, check the logs and see whether they look like they are related to your changes; if so, try to fix the problem by adding new commits to your pull request. Once the tests pass, hooray! 🎉
-
Relax and wait for feedback. We try to review contributions quickly and courteously. But we are human, and sometimes we get busy with other things or fail to notice an email; if it's been a while since you submitted your pull request, try posting a polite reminder about the existence of your pull request.
-
Discuss any feedback you receive as necessary. It's fine to defend your approach, but also be open to making changes based on suggestions you receive.
-
Sooner or later, the fate of your pull request will become clear. If it gets approved, an established contributor will merge it. It's not officially released into the wild until a contributor releases a new version of the package; if that doesn't happen quickly, don't hesitate to make an inquiry in case it's simply been overlooked.
From the whole team, thanks in advance for your contribution!
-
Revise is a package that tracks changes in source files and automatically updates function definitions in your running Julia session. Using it, you can make extensive changes without needing to rebuild the package in order to test your changes.
-
Debuggers can help you get to the root of a problem. There are many choices and interfaces:
- Juno has a polished GUI for debugging
- Debugger has a polished command-line interface
- Rebugger has an innovative but somewhat less-polished command-line interface
- Infiltrator offers more limited debugging, but often it's precisely what you need while avoiding the performance penalties that some of the other options suffer from.