CONTRIBUTING.md

Activity Browser Contributing Guidelines

How can I contribute?

There are several ways how you can contribute to the Activity Browser project:

• Reporting bugs
• Sharing ideas for new features
• Helping other users work with Activity Browser
• Contributing to the code of Activity Browser

Reporting bugs

If you notice a breaking bug or feature that doesn't work as expected, please see the Issues page on GitHub. On this page you can see if others have reported the same or similar issue. If someone already shared the same or a similar issue, just let us know you're experiencing the same problem. If you can't find an existing issue matching your problem, create a bug report. The bug report page will help you share the right information for us to help you.

Sharing ideas for new features

If you have an idea for a new feature or a logical extension on an existing one, don’t hesitate to share this through a feature request. Additionally, if you see other feature suggestions that look important or interesting for your work, add your voice!

Contributing documentation to the Activity Browser and helping other users

Youtube

The README file already contains a link to a youtube channel for introducing beginning users of the AB to the application. If you have the time, further contributions to further explain the more advanced features of the AB are especially welcome!

If you want to include the opening graphics created for the existing youtube videos, please contact the developers.

Wiki

The Activity Browser has its own wiki. This page contains an explanation of how to get started with the AB.

If you want to contribute to the wiki, either by adding figures or links or by writing new sections, please contact the developers!

Making changes to the wiki (for developers)

Any images or other assets in the documentation should be stored in docs/wiki/assets and linked to there instead of online links (unless copyrighted material is linked that cannot be shown in any other way). This way all assets are stored in the wiki git.

To make changes to the wiki, open a pull request with suggested changes to docs/wiki. While contributors with write access to Activity Browser can directly change the wiki, changes should instead be made to the files in docs/wiki (#1350).

The wiki can be updated in of 2 ways:

1. Merging a pull request and then manually triggering the wiki update action.
   • e.g. for fixing typos or making existing text clearer
2. When a new release is made, any changes will automatically be written to the wiki.
   • e.g. for new text related to a new feature release, which should only be visible when the feature is available

In-software guidance

With more and more features being included into the AB, the inclusion of in-software guidance for how these features work is becoming more and more a priority. Examples of in-software guidance go from ? buttons that explain the function of the tab/section, hover-text that show what buttons or drop-down menus do, through to in-depth warnings or error messages when something goes wrong when calculation or preparing data.

Helping other users

You can always try to help out our users by looking at our discussions page. If you would like to help other users in a more structured way, just contact the developers and lets discuss!

Developing the Activity Browser

If you want to contribute your time to make the activity browser better, great! If you don’t know where to start you can either have a look at the issues with a good first issue label or by contacting the developers.

For more in-depth information about contributing to the project, please read on.

Adding (big) features

If you want to make big changes to the code or functionality of Activity Browser, please always contact the developers first. A large amount of the code in the activity browser is based on the logic and features present in brightway2. If you have an idea for a new big feature you want to see in the activity browser, please (help us) work it out in a Jupyter notebook! This will give us a solid starting point on how to implement the feature in the activity browser as well as write tests for it!

What should I know before getting started?

The activity browser is an open-source project. On deciding you want to contribute to the activity browser, it might be unclear where in the code certain kinds of functionality or features are placed. This section is here to help give some direction.

• Controllers

  Controllers in the activity browser act as go-betweens for the Qt application and the underlying brightway layer. Ideally, these controllers are called exclusively through signals from the Qt application and will in turn call methods and classes that edit the structured data in brightway. If you want to present a warning or question to the user when they try and change brightway data, you can use a controller to do so.

• BW-Utils

  The code, methods and classes in the bwutils directory are kept separate from the rest of the application specifically because they are only dependent on-, and extensions of the brightway layer.
  Keeping a strict separation between brightway and the rest of the activity browser application allows for future changes to the brightway code to be handled in one place.

• Tables

  Tables in the activity browser are one of the more complex parts of the application as these are required to both present the data from brightway as well as handle the editing of this data (through the model embedded in the table class).

• Figures

  Figures constructed in the Activity Browser are currently implemented in matplotlib through either using pandas .plot or matplotlib directly. In the future we want to move to a different library, to make figures more interactive.

• Graphs

  These graphs are made up out of two parts, the python part which extracts information from brightway and prepares a JSON document, and the javascript part which presents a given JSON document as a graph (built using the JavaScript dagre D3 library).

Setting up a development environment

If you want to contribute code, we suggest the following setup:

• Set up a conda environment as explained in the readme
• Fork this repository and download your fork through git to your favourite IDE
• Set up this repository as an upstream remote like in the image below (for PyCharm):
  • Note that upstream can be named anything, but it is good convention to call it this

Running and writing tests

If you want to check whether your changes break anything essential, you can run the automated tests. This requires some additional packages.

conda install -n dev_ab pytest pytest-mock pytest-qt pytest-cov

You can then run the tests inside the repo like this:

# You can add the -v or --cov=activity_browser arguments to add additional
# information to the output of the test.
py.test
# OR
pytest
# OR
python -m pytest

An AB window will open and perform some automated actions. If you interfere, the tests will most likely fail. Also note that having multiple instances of the AB open can lead to unexpected responses.

In an ideal case, you can write your own tests for new features that you add. Please see the tests that are already present in the tests folder or look at the pytest-qt documentation for inspiration and examples.

Pull requests

Once you are happy with your changes to AB, please open a pull-request. We use the fork and pull model for external contributions. Fork the AB repository, create a new branch from the main branch, apply your changes on the new branch in your forked repository and open a pull request from there. When creating a pull-request, please add a description of what your new changes should accomplish (and if this wasn't a known problem, why AB needs this). If it's a larger pull-request, feel free to add screenshots/gifs or other useful descriptions to help us understand what you did. Next, make sure your pull-request has a sensible title that users can easily understand, this name is shown in the changelog of the next release. Avoid issue numbers in the title.

This is a BAD example of a title:

• This example is bad because it is not clear to users what this does and uses an issue number, which will show in the changelog, but also, does not work directly in titles.

This is a GOOD example of a title:

• This is a good example because it describes what is changed.

Finally, please make sure you follow the pull-request checklist (you can see this when you open a pull-request). If you can't complete certain tasks because you don't have write-access (e.g. adding a label and milestone), they will be performed by the maintainers.

Upon creating a new pull-request, there are a number of automated tests that will be run. If the test-runners fail in some way, it is likely that there is an error somewhere in your PR. You can look at the logs of the continuous integration services to see what failed and where.

When the tests pass on a pull-request, one of the maintainers of AB will review the changes (possibly requesting some edits) and approve or reject the request.

Do's and Don'ts

• Please do document any new code you wish to include in the activity browser. This means:
  • Writing useful documentation in the code (please follow the numpy style guide),
  • Writing useful tooltips, labels and other things that can help users in the software,
  • Updating the wiki in ./activity_browser/docs/wiki
• Where possible, avoid importing and using brightway2 classes and methods directly in the Qt application code. If some complex data processing is needed, see if your use-case is covered by bwutils instead. If bwutils does not contain any for your use-case you are welcome to add it.
• Always create changes on your own fork, even if you have write access to the main repository
• Do try to write descriptive commit messages:

  • This is a BAD example:

    

    • This is a bad example because looking back through the commit history, we don't know what this refers to
    • A better title could have been: implement dialog for new location linking feature

  • This is a GOOD example:

    

    • This is a good example because it is clear what has been done and where.
    • This commit message also uses a closing keyword, making writing your pull-requests easier because the issue is already linked automatically
    • This could have been better as 2 commits, one for resolving the issue, one for improving the documentation, it is not clear in the commit what actually fixes the issue.

  • Tip: Keep in mind that these commits are visible on Github, you can make use of this by referencing issues and using Markdown formatting in your commits.

Maintaining the Activity Browser

Next to developers, some people maintain the AB. Maintainers can contribute to AB themselves, but also have the following tasks:

• Review pull-requests made by others; not reviewing your own pull-requests should always be avoided, however small the changes
• Planning bug-fixes and features for release through milestones so the community knows what bug fixes and new features to expect in the next versions
• Creating new releases

Reviewing pull-requests

When reviewing a pull-request the below should be kept in mind. Consider that you're helping developers do better work and ensure the quality of AB, so be helpful; add/improve the basics and a milestone if they're missing.

Basics

• Is the title easy to understand for users?
• Is the checklist completed and have no things been removed that are relevant?
• Are the checklisted items correct? (e.g issues properly linked, correct label applied etc.)?

Necessity

• Do we need this change (e.g. is it from an open issue or clear from the pull-request why this is needed)?
• Does this conflict with other planned changes?

Code quality

• Is the code readable?
• Do the comments make sense?
• Is all the added code used?
• Is there still commented code that should be removed?
• Do the tests succeed and should new tests be added?

Functionality

• Try the new changes on your machine, does it do what it is supposed to do?
• Has nothing else accidentally broken because of this change?
• Try to abuse/break the new changes, better to find problems now than to have users find them.

Planning bug-fixes and new features

The AB team should schedule and prioritize bug-fixes and new features to be added to AB. By adding milestones to issues and pull-requests, it becomes clear to the community and other developers and maintainers what is planned for when. Using milestones also allows us to keep a log of when certain things have been added or removed from AB. While the releases changelog shows merged pull-requests, the milestones will also show issues that have been closed in a certain version making it easier to track when changes were made.

Once it has been decided that an issue will be worked on, it is useful to provide additional information in the issue:

• When: Adding a milestone
• Who: Assigning someone to the issue
• What: Commenting a TODO list with simple broken-down steps (e.g. like this)

Regular checks for dependency problems

AB has a canary install that runs the installation of AB every 24 hours, it will report any problems with installing AB.

In addition, the tests that run when a pull-request is opened can pass, while still having warnings, these may be DeprecationWarning or other things that are not a problem now, but will become a problem in the future.

If any installation problems occur or warnings happen in the pull-requests tests, they should be resolved.

Creating a new release of Activity Browser

Activity Browser versions and related information can be found on the releases page.

The AB follows the major.minor.patch versioning schema closely, but not entirely. Where major releases are reserved for completely backwards-incompatible changes, minor for new (non-breaking) features or improvements and patch for bug-fixes and minor changes.

To create a new release follow these steps:

• Review if all scheduled changes in the milestone for the next version are complete, if not, either re-plan them for a next milestone or finish them
• Do not close the milestone yet
• Check out the main branch (either through your IDE or with git checkout main)
• Fetch and Pull changes
• Create a new tag: git tag -a x.y.z -m 'x.y.z' (where x.y.z is the new version number)
• Push the new tag to the repository: git push upstream x.y.z
  • Of course make sure your upstream remote is actually called upstream
• The above triggers the following:
  • github actions creates a new release, showing all changes in a changelog
  • Within a few hours, the conda forge bot will notice a new release and open a new pull-request on our feedstock page
• Wait until a new pull-request is opened on the conda forge feedstock automatically, then review the pull-request and merge the changes
  • The release will be available on conda-forge shortly
• Close the milestone for this version
  • This triggers a github actions bot that will reply to each closed issue with this milestone that a new release is available with an implemented solution for the issue
• Write an email to the updates mailing list announcing the new changes

Don'ts for maintainers:

• Never create a new release on a Friday or on a day before you'll be unavailable
• Never create major or minor releases close to (e.g. 3 weeks before) something like a course where AB is used, only release changes that are certain to improve stability or fix things that are known to be a problem during the course
• In general, don't make releases more than once every two weeks, of course if there are urgent fixes, make them