Skip to content

Commit

Permalink
update .github docs for easier contributions
Browse files Browse the repository at this point in the history
  • Loading branch information
@444B
444B committed Dec 22, 2024
1 parent 1db6d07 commit 9f5c9a5
Show file tree
Hide file tree
Showing 4 changed files with 146 additions and 210 deletions.
184 changes: 62 additions & 122 deletions .github/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,128 +1,68 @@

# Contributing to Streamlit-Analytics

We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:

- Reporting a bug
- Discussing the current state of the code
- Submitting a fix
- Proposing new features
- Becoming a maintainer

## We Develop with GitHub

We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.

## We Use GitHub Flow

All code changes happen through pull requests, so we suggest you familiarize yourself with [GitHub Flow](https://guides.github.com/introduction/flow/). Pull requests are the best way to propose changes to the codebase. We actively welcome your pull requests:

1. Fork the repo and create your branch from `main`. **Make sure to start your branch with the word "test/"**
2. Make sure your code lints by running tests on the code (described below)
3. Issue that pull request!

## Any contributions you make will be under the same license as the project

In short, when you submit code changes, your submissions are understood to be under the same [license](LICENSE.md) that covers the project. Feel free to contact the maintainers if that's a concern.

## Report bugs using Github's [issues](https://github.com/444B/streamlit-analytics2/issues/new/choose)

We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/444B/streamlit-analytics2/issues/new/choose); it's that easy!

**Great Bug Reports** tend to have:

- A quick summary and/or background
- Steps to reproduce
- Be specific!
- Give sample code if you can.
- What you expected would happen
- What actually happens
- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)

## Use a Consistent Coding Style

- We follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide for Python code.
<!-- - Ensure your code passes the run_checks.sh (described below)
``` -->

## License

By contributing, you agree that your contributions will be licensed under its [License](LICENSE.md).
# Contributing to Streamlit-Analytics2

We appreciate your interest in contributing to Streamlit-Analytics2! This guide will walk you through the process of setting up your development environment and submitting a pull request.

## Getting Started

1. Fork the repository on GitHub.
2. Clone your forked repository to your local machine.
```sh
git clone https://github.com/444B/streamlit-analytics2.git
cd streamlit-analytics2
```
3. Create a new branch for your changes. Make sure to start the branch name with "test/".
```sh
git checkout -b test/your-feature-name
```
4. Set up your development environment (see below).
5. Make your changes and test them locally.
6. Commit your changes and push them to your forked repository.
```sh
git add .
git commit -m "Your commit message"
git push origin test/your-feature-name
```
7. Open a pull request on the main repository.

## Setting Up Your Development Environment

### 1. Clone the Repository
Navigate to the directory where you want to clone the repo and run:
```sh
git clone https://github.com/444B/streamlit-analytics2.git
cd streamlit-analytics2
```

### 2. Create a New Branch
Create a new branch for your work:
```sh
git checkout -b name_of_your_new_branch
```
> **IMPORTANT**: Start the name of your branch with "test/". Pushing on this branch will trigger a release to [TestPyPI](https://test.pypi.org/project/streamlit-analytics2/) where we can further verify that the code works as expected.
### 3. Install Python and pipenv
Ensure you have Python 3.10.x installed, then install pipenv:
```sh
pip install --user pipenv
```

### 4. Create a Pipenv Environment
Set up your pipenv environment with Python at least python 3.10.
A higher version should be fine unless you are using cutting edge python expressions.
```sh
pipenv --python 3.10
```
1. Make sure you have Python 3.12.x installed.
2. Install pipenv.
```sh
pip install --user pipenv
```
3. Create a pipenv environment and install dependencies.
```sh
pipenv --python 3.12
pipenv install --dev
```
4. Activate the virtual environment.
```sh
pipenv shell
pipenv update
```
5. Run a minimal example to ensure everything is set up correctly.
```sh
streamlit run examples/minimal.py
```

## Before Submitting Your Pull Request

1. Make sure your code follows the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide.
2. Run the provided checks to ensure your code is compliant.
```sh
cd tests/
chmod +x /run_checks.sh
./run_check.sh
```
This will perform formatting and checks using black, isort, flake8, mypy, bandit, and pytest.

## Reporting Issues

If you encounter a bug or have a feature request, please submit an issue on the [GitHub issue tracker](https://github.com/444B/streamlit-analytics2/issues/new/choose). Be sure to provide a clear description and steps to reproduce the issue if applicable.

### 5. Install Dependencies
Install all necessary project dependencies. If you are writing/editing code, it is **highly** reccomended that to get the dev packages. You will need them if you intend on contributing code.
```sh
pipenv install --dev
```

### 6. Activate the Virtual Environment
Activate your pipenv environment:
```sh
pipenv shell
pipenv update
```

### 7. Write code, test new features!
Please note that the ```examples/minimap.py``` file is set to detect your file path and use the local code for ```streamlit_analytics2``` instead of a pip installed version. Just change the code in ```src/streamlit/analytics2/...py``` and it should be used in the example files.
>[!NOTE]Sometimes you might need to CTRL+C and restart streamlit. I havent yet figured out why save+rerun isnt working as expected.
### 8. Run a Minimal Example
Start with running a minimal Streamlit app to ensure everything is set up correctly:
```sh
streamlit run examples/minimal.py
```

### 9. Before submitting
- Our code goes through robust checks to ensure safety and high quality. Our [workflows](https://github.com/444B/streamlit-analytics2/actions) are set up to detect issues in code and will fail a deployment if any issues are detected.
- To prevent lost time when reviewing the PR, please run the local test bash file to ensure that code in compliant.
```sh
cd tests/
chmod +x /run_checks.sh
./run_check.sh
```

This will perform formatting and checks with the following packages:
- black (code formatting)
- isort (sorting imports)
- flake8 (Linting)
- mypy (Static type checking)
- bandit (Security scanning)
- pytest (test coverage)

## Additional Tips
## License

- **Troubleshooting**: If you encounter any issues, please check common pipenv errors and their solutions.
- **Making Contributions**: After testing your changes, commit them to your branch, push to your fork, and open a pull request against the main repository.
- **Environment Variables**: If the project requires specific environment variables, set them up according to the project documentation.
- **Testing and Linting**: Before submitting your pull request, ensure you run any tests and lint your code according to the project's guidelines.
By contributing to this project, you agree that your contributions will be licensed under the same [license](LICENSE.md) as the project.

Thank you for contributing to streamlit-analytics2!
Thank you for contributing to Streamlit-Analytics2! Your efforts help make this project better for everyone.
49 changes: 25 additions & 24 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,35 @@
# Pull Request Template
## Description

## TL;DR
Provide a brief summary of the changes made.
-
Briefly describe the changes made in this pull request.

## Problem Solved
1. Describe the problem your changes address.
2. Please mention the issue number if relevant
-
-
## Related Issue(s)

## Screenshots
If applicable, add screenshots to help explain your solution. For adding images, use:
-
- Closes #[issue number]

## Changes Made(Optional)
List the main changes in bullet points.
## Changes Made

- [ ] Change 1...
- [ ] Change 2...
- [ ] ...
- [ ] Change 1
- [ ] Change 2
- [ ] Change 3

## Manual Testing
- [ ] You have manually tested all changes to ensure they work as intended. Replace the [ ] with a [X] if True.
## Testing

- [ ] I have manually tested these changes and confirm they work as intended.

**How was this tested?**
Describe the tests that you ran to verify your changes.
-
**Testing Details:**
Describe how you tested the changes.

## Screenshots (if applicable)

Add any relevant screenshots here.

## Checklist

- [ ] I have read the [CONTRIBUTING](CONTRIBUTING.md) guide.
- [ ] I have commented my code, particularly in hard-to-understand areas.
- [ ] I have made corresponding changes to the documentation (README.md, CONTRIBUTING.md, etc.).
- [ ] My changes generate no new warnings or errors.

## Additional Notes
Include any additional information that might be relevant for reviewers.
-

Add any other notes or context about the pull request here.
82 changes: 25 additions & 57 deletions .github/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,78 +11,46 @@

**Enhanced tracking & visualization for your Streamlit apps.**

`streamlit-analytics2` is a fork and extension of the original [streamlit-analytics](https://github.com/jrieke/streamlit-analytics), aimed at improving and securing the analytics functionality within Streamlit applications. With minimal setup, track user interactions and visualize analytics directly in your browser, akin to Google Analytics but tailored for Streamlit.

This fork was initiated due to the inability to collaborate directly on the upstream project, which currently has several unresolved security issues and bugs. Our intention is to maintain a positive relationship with the original project and its creator, focusing on enhancing the tool's reliability and security for the community.
Streamlit Analytics2 is maintained, powerful tool for tracking user interactions and gathering insights from your Streamlit applications. With just a few lines of code, you can start monitoring user behavior and making data-driven decisions to improve your app.

> [!Note]
> This fork is confirmed to fix the deprecation ```st.experimental_get_query_params``` alerts. [Context](https://docs.streamlit.io/library/api-reference/utilities/st.experimental_get_query_params)
> It also resolved 25 security issues that exist in the upstream (2 Critical, 11 High, 10 Moderate, 2 Low)
<sup>This project is in active development. We welcome contributions and address security concerns on a best-effort basis, with details available in our [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) respectively.</sup>


## Installation

```bash
pip install streamlit-analytics2
```

## Migration from upstream streamlit-analytics

Only two single characters need to be changed and this has been tested and verified to work.
1. Change your requirements.txt or other dependency file to use 'streamlit-analytics**2**'. Just add a '2'
2. Change your code import to use 'streamlit_analytics**2** as streamlit_analytics'. Also, just add a '2'. Seen below.

> [!IMPORTANT]
> This project aims to be backwards compatible with the upstream and migration literally just means adding the number 2 and getting the new package.
> The above steps should be sufficient but if you need more steps, check out our [Migration Guide](https://github.com/444B/streamlit-analytics2/wiki/0.--Migration-Guide-from-streamlit%E2%80%90analytics-to-streamlit%E2%80%90analytics2).
## Getting Started

## How to Use
1. Install the package:
```
pip install streamlit-analytics2
```

Simple integration with any Streamlit app:
2. Import and initialize the tracker in your Streamlit script:
```python
from streamlit_analytics2 import track

with track():
# Your Streamlit app code here
```

```python
import streamlit as st
import streamlit_analytics2 as streamlit_analytics
3. Run your Streamlit app and append `?analytics=on` to the URL to view the analytics dashboard.

with streamlit_analytics.track():
st.write("Hello, World!")
st.button("Click me")
```

All interactions are now tracked, supporting all standard Streamlit widgets.

Another way to get the tracking is to call the streamlit_analytics.track() on your main() function:
```python
import streamlit as st
import streamlit_analytics2 as streamlit_analytics

with streamlit_analytics.track():
main()

def main():
st.write("Hello, World!")
st.button("Click me")
```
Using streamlit_analytics.track() is the recommended method and will become the primary way to initiate streamlit-analytics2 after the [upcoming v.1.0.0](https://github.com/444B/streamlit-analytics2/issues/53) release.
## Contributing

## Moving Forward
We're actively seeking additional maintainers to help improve Streamlit Analytics2. If you're interested in contributing, please check out our [Contributing Guidelines](CONTRIBUTING.md) to get started. We welcome pull requests, bug reports, feature requests, and any other feedback.

- **TODOs and Feature Requests**: We've transitioned our roadmap and feature requests to [GitHub Issues](https://github.com/your-repo/streamlit-analytics2/issues). Feel free to contribute ideas or report bugs!
- **Advanced Configuration**: Detailed guidance on advanced setup (including password protection and database integration) options are available in our [Project Wiki](https://github.com/444B/streamlit-analytics2/wiki).
- **Improved Performance**: We are focused on providing a use of streamlit-analytics2 that doesn't impact the performance of your app.
All suggestions and inputs are welcome on our [forum](https://github.com/444B/streamlit-analytics2/discussions)

## Contributing
## Upcoming Features

Your contributions are welcome! Please refer to our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to make a difference.
The step by step guide will show you how to set up a dev environment, testing standards and how to make a PR.
We're currently working on a major breaking release that will introduce exciting new features and enhancements:

## Security
- Multi-page tracking: Monitor user interactions across multiple pages of your Streamlit app.
- Improved metrics accuracy: Get more precise and reliable usage metrics.
- Flexible data formats: Choose between CSV or JSON for storing and exporting analytics data.
- Customization screen: Easily configure and customize the analytics settings through a user-friendly interface.

We prioritize the security of our users' data. For reporting security vulnerabilities or for more information, please review our [SECURITY.md](SECURITY.md).
Stay tuned for more updates and join our community to be part of shaping the future of Streamlit Analytics2!

## Acknowledgments
## License

A special thanks to [jrieke](https://github.com/jrieke) and all contributors to the original `streamlit-analytics` project. Your work has inspired continued innovation and community collaboration.
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information.
Loading

0 comments on commit 9f5c9a5

Please sign in to comment.