Contributing

Development Dependencies

Python 3 (versions 3.6 to 3.8 are currently supported)
pip install pylint pytest pytest-cov pre-commit python-dateutil
- pylint to check for errors and to enforce code style.
- pytest to run the tests.
- pytest-cov to check for code coverage.
- pre-commit to automate code style checks.
- python-dateutil to resolve timezone-related issues in the tests.
If you’re making changes to the documentation, install the documentation dependencies: pip install -r docs/requirements.txt.
- Refer this for a brief introduction to ReST.

Development Process - Short Version

Select an issue to work on, and inform the maintainers.
Fork the repository.
git clone the forked version of the project.
Work on the master branch for smaller patches and a separate branch for new features.
Initialize pre-commit hook (only on first commit) by running: pre-commit install
Make changes, git add and then commit. Make sure to link the issue number in the commit message.
Run the following commands: pylint browser_history, pytest --cov=./browser_history
(Optional) If you’re updating the documentation, make sure you update docs/quickstart.rst and README.md simultaneously. Run the following: cd docs, make html and then open _build/html/index.html in a browser to confirm that the documentation rendered correctly.
If all tests are passing, pull changes from the original remote with a rebase, and push the changes to your remote repository.
Use the GitHub website to create a Pull Request and wait for the maintainers to review it.

Development Process - Long Version

Select an issue to work on, and inform the maintainers.
- Look for issues, find something that you want to work on.
- Leave a comment on the issue saying that you want to work on it. The maintainers will give you the go-ahead.
Fork the repository.
- The fork button will be available on the top right in the GitHub website.
git clone the forked version of the project.
- git clone https://github.com/<your-github-username>/browser-history.git
- Add a remote to the original repository and name it upstream.
- git remote add upstream https://github.com/browser-history/browser-history.git
Work on the master branch for smaller patches and a separate branch for new features.
- To create a new feature branch and use it, run: git checkout -b feature-<feature-name>.
- If a feature branch already exists, switch to it before committing: git checkout feature-<feature-name>
Initialize the pre-commit hook, if you are committing changes for the first time:
- pre-commit install - to setup git hook scripts that will help you check your code each time you commit.
Make changes, git add and then commit. Make sure to link the issue number in the commit message.

Caution

When testing changes, create and activate a virtual environment and install the package in editable mode using pip install -e . to ensure that the pip version is not used.
- git add <names of all modified files>
- git commit
- Make your commit descriptive. The above command will open your text editor.
- (optional) Tag the commit with appropriate tags such as: (see git log for examples)
  - [CODE] - changes to the main code (other than CLI)
  - [CLI] - changes to the CLI code
  - [FIX] - bug fixes
  - [TESTS] - updates to tests
  - [CI] - changes related to integrations such as GitHub actions workflows, codecov, etc.
  - [DOC] - changes to the documentation
- Continuing the above theme, it is preferred to add changes to a single part in one commit. For example, changes to the code, tests and docs for the same feature could go into separate commits.
- Write the commit message on the first line and a short description about your change. Save and quit the editor to commit your change.
Run the following commands:
- pylint browser_history - ensure that there are no errors (codes starting with an E).
- pytest --cov=./browser_history - ensure that all tests pass.
(Optional) If you’re updating the documentation, run the following:

Caution

Update docs/quickstart.rst and README.md simultaneously.
- Change to the docs directory: cd docs
- Build the documentation: make html
- Open _build/html/index.html in a browser to confirm that the documentation rendered correctly.
If all tests are passing, pull changes from the original remote with a rebase, and push the changes to your remote repository.

Caution

If you are working on a feature branch, use that branch name instead of master.
- git pull --rebase upstream master
- In the extremely small chance that you run into a conflict, just open the files having the conflict and remove the markers and edit the file to the one you want to push. After editing, run git rebase --continue and repeat till no conflict remains.
- Verify that your program passes all the tests, and your change actually works in general.
Caution

If you are working on a feature branch, use that branch name instead of master.
- Push your changes to your fork: git push origin master
Use the GitHub website to create a Pull Request and wait for the maintainers to review it.
- Visit your forked repository and click on “Pull Request”. The Pull Request must always be made to the browser-history/master branch. Add the relevant description, ensure that you link the original issue.
- The maintainers will review your code and see if it is okay to merge. It is quite normal for them to suggest you to make some changes in this review.
- If you are asked to make changes, all you need to do is:
```
# make your change
git add <files that you changed>
git commit
git push origin master      # if you are working on a feature branch, use that branch name instead of master
```
- The changes are immediately reflected in the pull request. Once the maintainers are satisfied, they will merge your contribution :)

As long as you follow the above instructions things should go well. You are always welcome to ask any questions about the process, or if you face any difficulties in the #browser-history-help channel on the PES Open Source Slack .

Release Overview

(for the more regular contributors)

master branch for development. Small patches/enhancements go here.
release branch for tagged releases. This is the branch that will be shipped to users.
Separate feature-x branches for adding new “big” features. These branches are merged with master, on completion.
Once we are satisfied with a certain set of features and stability, we pull the changes from master to release. A new release tag is made.
- The release workflow will automatically submit the release to PyPI. Ensure that version numbers are changed where necessary (setup.py, docs, etc.) - PyPI does not accept new files for the same version number, once a version is published it cannot be changed.
If bugs were found on the stable release, we create a hotfix branch and fix the bug. The master branch must also pull the changes from hotfix. A new release tag is created (incrementing with a smaller number).
- We follow semantic versioning .

Code of Conduct

This project follows the PES Open Source Code of Conduct .

Technicalities

(might be outdated)

Adding support for a new browser

Browsers are defined in browser_history/browsers.py. To add a new browser, create a new class extending the browser_history.generic.Browser. See Browser Functionality for the class variables that must be set and their description. Currently only browsers which use SQLite databases to store history are supported.

Adding support for a new platform

(platform here refers to an OS)

This one is tricky. Platforms are defined in browser_history.utils.Platform. To add a new platform, the following must be updated.

Add the platform to browser_history.utils.Platform
Update browser_history.utils.get_platform() to correctly return the platform.
Update the __init__ method of browser_history.generic.Browser and create a new class variable for that platform.
Update as many Supported Browsers as possible with the platform_path for the new platform.

Tests

Test Home directory:

Tests are done by including a minimal copy of the browser files with the correct paths. For example, on Linux platform and for the Firefox browser, tests/test_homedirs/Linux contains a minimal snapshot of the home directory with only the files required for extracting history which is the following for Firefox on Linux:

test_homedirs/Linux
└── .mozilla
    └── firefox
        └── profile
            └── places.sqlite

It would be a great help for us if you contribute any missing platform-browser combination, even if you don’t write any tests accompanying them.

Writing Tests:

Tests are executed using pytest. Monkeypatching is used to change the home directory to one of the test directories and to emulate the home directory of a different platform.

The monkeypatches are defined in tests/utils.py. The change_homedir fixture must be used for all tests and one of become_windows, become_mac or become_linux. Look at some tests in tests/test_browsers.py for examples.