Skip to content

CONTRIBUTING.rst

Latest commit

 

History

History
342 lines (218 loc) · 10.2 KB

CONTRIBUTING.rst

File metadata and controls

342 lines (218 loc) · 10.2 KB
Raw

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/ShortestPathLab/flatland/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the Repository Issue Tracker for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.

Implement Features

Look through the Repository Issue Tracker for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.

Write Documentation

flatland could always use more documentation, whether as part of the official flatland docs, in docstrings, or even on the web in blog posts, articles, and such. A quick reference for writing good docstrings is available at : https://docs.python-guide.org/writing/documentation/#writing-docstrings

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/ShortestPathLab/flatland/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here's how to set up flatland for local development.

  1. Fork the flatland repo on https://github.com/ShortestPathLab/flatland .

  2. Clone your fork locally:

    $ git clone git@github.com:ShortestPathLab/flatland.git

  3. Install the software dependencies with uv. (This assumes you have uv installed by following the instructions here. You do not need to install Python yourself — uv reads .python-version and provisions the right interpreter for you.)

    $ uv sync

    This creates a .venv virtual env from uv.lock, with the project and all development dependencies installed.

  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. When you're done making changes, check that your changes pass ruff and the tests:

    $ uv run ruff check flatland tests examples benchmarks
$ uv run pytest

    uv run ruff check --fix applies the safe fixes automatically, and uv run ruff format reformats the code.

    Prefixing a command with uv run runs it inside the project virtual env, re-syncing it first if the lockfile changed. Alternatively, activate .venv yourself and drop the prefix.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "Addresses #<issue-number> Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

  7. Submit a pull request through the GitHub repository website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.md.
  3. The pull request should work for Python 3.14. Make sure that the tests pass before asking for a review.
  4. Although we cannot enforce it technically, we ask for pull requests to be reviewed by at least one core member in order to ensure that the Technical Guidelines below are respected and that the code is well tested.
  5. When a pull request is merged, source branches should be deleted and commits squashed.

Tips

To run a subset of tests:

$ py.test tests.test_flatland

Releasing

A reminder for the maintainers on how to cut a release. Flatland is not published to a package index; a release is simply a tagged commit that users install from GitHub. Make sure all your changes are committed, then run:

$ bumpversion patch # possible: major / minor / patch
$ git push
$ git push --tags

Technical Guidelines

Clean Code

Please adhere to the general Clean Code principles, for instance we write short and concise functions and use appropriate naming to ensure readability.

Naming Conventions

We use the pylint naming conventions:

module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_CONSTANT_NAME, global_var_name, instance_var_name, function_parameter_name, local_var_name.

numpydoc

Docstrings should be formatted using numpydoc.

Acessing resources

We use importlib-resources to read from local files.

Sample usages:

from importlib_resources import path

with path(package, resource) as file_in:
    new_grid = np.load(file_in)

And:

from importlib_resources import read_binary

load_data = read_binary(package, resource)
self.set_full_state_msg(load_data)

Renders the scene into a image (screenshot)

renderer.gl.save_image("filename.bmp")

Type Hints

We use Type Hints (PEP 484) for better readability and better IDE support.

Have a look at the Type Hints Cheat Sheet to get started with Type Hints.

Caveat: We discourage the usage of Type Aliases for structured data since its members remain unnamed.

NamedTuple

For structured data containers for which we do not write additional methods, we use NamedTuple instead of plain Dict to ensure better readability by

Members of NamedTuple can then be accessed through .<member> instead of ['<key>'].

If we have to ensure some (class) invariant over multiple members (for instance, o.A always changes at the same time as o.B), then we should uses classes instead, see the next section.

Class Attributes

We use classes for data structures if we need to write methods that ensure (class) invariants over multiple members, for instance, o.A always changes at the same time as o.B. We use the attrs class decorator and a way to declaratively define the attributes on that class:

Abstract Base Classes

We use the abc class decorator and a way to declaratively define the attributes on that class:

And then

# abc_subclass.py

import abc
from abc_base import PluginBase


class SubclassImplementation(PluginBase):

    def load(self, input):
        return input.read()

    def save(self, output, data):
        return output.write(data)


if __name__ == '__main__':
    print('Subclass:', issubclass(SubclassImplementation,
                                  PluginBase))
    print('Instance:', isinstance(SubclassImplementation(),
                                  PluginBase))

Currying

We discourage currying to encapsulate state since we often want the stateful object to have multiple methods (but the curried function has only its signature and abusing params to switch behaviour is not very readable).

Thus, we should refactor our generators and use classes instead.