Hey, you! I want you to contribute! If you think HyperparameterHunter doesn't need or want your contribution, let me assure you that is not the case. We will gladly accept any form of contribution you can offer, no matter how seemingly insignificant it might seem. No contribution is insignificant, and all your help is greatly appreciated. I look forward to working with you to make HyperparameterHunter the revolutionary hyperparameter optimization library I know it can be. But it can't get there without your help!
In order to develop HyperparameterHunter, follow these steps to setup your environment:
- Fork HyperparameterHunter on GitHub
- Clone the Git repo:
$ git clone https://github.com/$USERNAME/hyperparameter_hunter $ cd hyperparameter_hunter - Setup the virtual environment with dependencies and development tools
$ make dev $ source env/bin/activate - Format your code (using Black and isort), then run linter, and unit tests
$ make format $ make lint test
If you've noticed that your favorite machine learning library isn't listed anywhere in the README, or it does'nt have any examples in the 'examples' directory, test it out! If it works, awesome! Let us know, and maybe write an example for it, so we can include it in our list of tested libraries. If it doesn't work, also let us know, and try to figure out what might be necessary to get that one special library to work with HyperparameterHunter.
Head over to the repository's issue tracker, and start reporting bugs and suggesting enhancements! Please search for closed and open issues before opening new ones! All new issues should comply with the following guidelines:
- Absolutely, definitely not a duplicate issue
- Appropriately labeled
- For feature requests, provide example use cases and explain why you need the feature
- For bug reports, provide information about your configuration (OS, versions, etc.) and a script
to reproduce the issue
- Script should be a minimal, complete, and verifiable example, and runnable as-is
Organization of issues is critical. Therefore, any help assigning priorities and other labels to issues is a valuable contribution. Labeling duplicated issues is also very helpful to ensure a neat and tidy issue tracker that helps us get the important stuff done. This organization of issues also includes showing your support for issues that you feel are important in order to draw more attention to them.
If you want to ease into your first code contribution, these are some good places to start:
- Unit Tests
- More tests to ensure HyperparameterHunter is running smoothly is always a good thing
- Use Python's Coverage tool to determine which modules need tests
coverage run --source=hyperparameter_hunter setup.py test- Might help to add the following flag:
--omit=hyperparameter_hunter/env/*
- Documentation
- Look for issues with a "Documentation" label
- Use DocstrCoverage to quickly find code that needs documentation
docstr-coverage hyperparameter_hunter --skipmagic --skipclassdef- Might help to add the following flag:
--exclude='env/*|HyperparameterHunterAssets/*'
- "Easy" Issues
- Look for issues that have an "Easy" label, or for issues that sound easy to you
- Also, check this board for our todo list, including more long-term contributions
HyperparameterHunter uses Black code formatting, and compliance is verified for all
commits. One notable modification to the Black defaults, is line-length, which is set to a
maximum of 100. Aside from Black's style conventions, what follows are a few additional stylistic
choices for HyperparameterHunter:
Naming should be as descriptive as necessary. This can result in what some might consider to be overly-verbose variable names, but they are formatted this way to convey the role of the variable as clearly as possible. Classes should be named following CamelCase conventions, with the first letter capitalized. All other variables should be named following snake case conventions, using all lowercase letters, with words separated by underscores.
String formatting should be done using '{}'.format() syntax, or using f-strings. Do not use
"old style" string formatting (% operator).
Imports should be formatted thusly:
# <special imports (like __future__) go here if necessary>
##################################################
# Import Own Assets
##################################################
# <hyperparameter_hunter imports go here>
# ...
##################################################
# Import Miscellaneous Assets
##################################################
# <miscellaneous imports go here>
# ...
##################################################
# Import Learning Assets
##################################################
# <imports from machine learning libraries go here>
# ...Imports within each of the three sections should be ordered alphabetically (A-Z, preceded by
punctuation marks and numbers). The alphabetical ordering should be done with respect to the
module name, then to the assets being imported. When ordering imports, disregard the import
statement style: import ..., or from ... import .... Each of the three sections is separated
by a single newline, and each of the section border lines consists of 50 consecutive octothorpe
characters.
Normal comments should start with a single octothorpe character, and a single space, followed by the comment content. Capitalization should follow standard sentence capitalization rules, without ending punctuation. Variable names are exempt from the capitalization rules.
Todo, and flag comments should be formatted as follows:
# TODO: <Comment content>
# FLAG: <Comment content>The three-line title comments described in the above Import Style Guide can also be used to mark significant separations in code. As noted above, they should span three lines, in which the first and third lines consist solely of 50 octothorpe characters, and the second line starts with a single octothorpe and a space, followed by the comment content. The comment content in the second line should be capitalized according to APA title capitalization guidelines.
Single-line subtitle comments can also be used to mark other separations in code for clarity. They should span a single line and start with 20 octothorpe characters, followed by a space, followed by the comment content, then ending with a space, followed by 20 octothorpes. Just like the three-line title comments described above, comment content should be capitalized according to APA title capitalization rules (except for variable names). They are formatted thusly:
#################### <Comment Content> ####################For examples of both the three-line title comments, and the single-line subtitle comments,
see :mod:`hyperparameter_hunter.environment`
All code contributions must be documented in accordance with these guidelines. We use NumPy-style docstrings. For examples on proper docstring-formatting, refer to almost any docstring in the repository, or to these example docstrings, or this guide.
All documented parameters, return values, yield values, etc. should include a description of the value, in addition to its name and type. These values should also be documented in the order of their appearance in the code.
Wherever appropriate, include cross-references to modules, classes, methods, functions, and
attributes. There are plenty of examples of this in the repository, but the general form is
:role:`identifier` , in which identifier is a period-separated path to the object being
referenced, and role is one of the following columns that correspond to the value below it:
| mod | class | meth | func | attr |
|---|---|---|---|---|
| module | class | method | function | attribute |
For additional information, see this guide
When documenting classes, barring extenuating circumstances, the class should be documented in its
:meth:`__init__` , rather than below the class definition itself.
Files should include module docstrings at the top of the file that include a description of the module's purpose/tasks. Usually, module docstrings should include a "Related" section, identifying other modules to which the module is related. If appropriate, a "Notes" section may be included as well to draw attention important information.
See the module docstring of :mod:`hyperparameter_hunter.experiments` for an example.