|
| 1 | +# Contributing to Metalhead.jl |
| 2 | + |
| 3 | +We welcome contributions from anyone to Metalhead.jl! Thank you for taking the time to make our ecosystem better. |
| 4 | + |
| 5 | +You can contribute by fixing bugs, adding new models, or adding pre-trained weights. If you aren't ready to write some code, but you think you found a bug or have a feature request, please [post an issue](https://github.com/FluxML/Metalhead.jl/issues/new/choose). |
| 6 | + |
| 7 | +Before continuing, make sure you read the [FluxML contributing guide](https://github.com/FluxML/Flux.jl/blob/master/CONTRIBUTING.md) for general guidelines and tips. |
| 8 | + |
| 9 | +## Fixing bugs |
| 10 | + |
| 11 | +To fix a bug in Metalhead.jl, you can [open a PR](https://github.com/FluxML/Metalhead.jl/pulls). It would be helpful to file an issue first so that we can confirm the bug. |
| 12 | + |
| 13 | +## Adding models |
| 14 | + |
| 15 | +To add a new model architecture to Metalhead.jl, you can [open a PR](https://github.com/FluxML/Metalhead.jl/pulls). Keep in mind a few guiding principles for how this package is designed: |
| 16 | + |
| 17 | +- reuse layers from Flux as much as possible (e.g. use `Parallel` before defining a `Bottleneck` struct) |
| 18 | +- adhere as closely as possible to a reference such as a published paper (i.e. the structure of your model should be intuitive based on the paper) |
| 19 | +- use generic functional builders (e.g. [`resnet`](#) is the core function that build "ResNet-like" models based on the principles in the paper) |
| 20 | +- use multiple dispatch to add convenience constructors that wrap your functional builder |
| 21 | + |
| 22 | +When in doubt, just open a PR! We are more than happy to help review your code to help it align with the rest of the library. After adding a model, you might consider adding some pre-trained weights (see below). |
| 23 | + |
| 24 | +## Adding pre-trained weights |
| 25 | + |
| 26 | +To add pre-trained weights for an existing model or new model, you can [open a PR](https://github.com/FluxML/Metalhead.jl/pulls). Below, we describe the steps you should follow to get there. |
| 27 | + |
| 28 | +1. Train your model or port the weights from another framework. |
| 29 | +2. Save the model using [BSON.jl](https://github.com/JuliaIO/BSON.jl) with `BSON.@save "modelname.bson" model`. It is important that your model is saved under the key `model`. |
| 30 | +3. Compress the saved model as a tarball using `tar -cvzf modelname.tar.gz modelname.bson`. |
| 31 | +4. Obtain the SHAs (see the [Pkg docs](https://pkgdocs.julialang.org/v1/artifacts/#Basic-Usage)). Edit the `Artifacts.toml` file in the Metalhead.jl repository and add entry for your model. You can leave the URL empty for now. |
| 32 | +5. Open a PR on Metalhead.jl. Be sure to ping a maintainer (e.g. `@darsnack`) to let us know that you are adding a pre-trained weight. We will create a model repository on HuggingFace if it does not already exist. |
| 33 | +6. Open a PR to the [corresponding HuggingFace repo](https://huggingface.co/FluxML). We will merge your PR. |
| 34 | +7. Copy the download URL for the model file that you added to HuggingFace. Make sure to grab the URL for a specific commit and not for the `main` branch. |
| 35 | +8. Update your Metalhead.jl PR by adding the URL to the Artifacts.toml. |
| 36 | +9. If the tests pass for your weights, we will merge your PR! |
| 37 | + |
| 38 | +If you want to fix existing weights, then you can follow the same set of steps. |
0 commit comments