From 7faaa3b5bbdc737ccf0bc3f46ff8bf8e1772b182 Mon Sep 17 00:00:00 2001 From: CohenAdkins <87725113+CohenAdkins@users.noreply.github.com> Date: Wed, 25 Sep 2024 21:56:52 -0400 Subject: [PATCH] Update README.rst Spaced out the readme into more sections for more readability. Added the how to contribute section and guidelines sections to enable those who would like to add to the project be welcome to do so. Added features section to showcase what the project has in store for viewers. --- README.rst | 164 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 122 insertions(+), 42 deletions(-) diff --git a/README.rst b/README.rst index 7734e4e..6c2a941 100644 --- a/README.rst +++ b/README.rst @@ -1,60 +1,140 @@ -===================== Welcome to Bluepass!! ===================== -Bluepass is a secure password manager with peer-to-peer sync built in. -Currently it is an early beta version, and needs to be installed from source. +Bluepass is a secure password manager with peer-to-peer sync built in. Currently it is an early beta version and needs to be installed from source. +A brief description of what this project does and who it's for. -Generic installation instructions +Generic Installation Instructions ================================= -The instructions below are generic installation instructions. You can find -specific instructions for Ubuntu and Fedora further down. Bluepass should work -on any recent Linux distribution. It should also work on Mac OSX and Windows, -but on these platforms P2P sync is not yet available. - -* Make sure you have a supported version of Python installed. The preferred - version is Python 3.3, but 2.7 and 2.6 also work. -* Make sure you can compile and install C extensions for Python. This means - that you need Python development files, a C compiler, make and pip. You - also need git to check out the Bluepass source code. -* Install dependencies: PyQt4, libffi including development files and openssl - including development files. -* If you want to install in a virtualenv, set one up and activate it. -* Clone the sources from Github: ``git clone https://github.com/geertj/bluepass`` -* ``pip install -r requirements.txt`` from the bluepass directory. -* ``python setup.py install`` +To install **Bluepass**, follow the instructions below. Specific steps for **Ubuntu** and **Fedora** are provided further down. Bluepass is designed to work on most recent **Linux distributions**, and while it can run on **macOS** and **Windows**, the **peer-to-peer sync** feature is not yet available on these platforms. + +Step-by-Step Guide +------------------- + +1. **Check Python Version:** + - Ensure you have a supported version of Python installed. Bluepass works best with **Python 3.3**, though versions **2.7** and **2.6** are also supported. + +2. **Set Up Python Development Environment:** + - You'll need to compile and install **C extensions** for Python. This requires: + - **Python development files** + - A **C compiler** + - `make` + - `pip` + - Additionally, you’ll need **git** to clone the Bluepass source code from GitHub. + +3. **Install Required Dependencies:** + - Make sure the following dependencies are installed: + - **PyQt4** + - **libffi** (with development files) + - **OpenSSL** (with development files) + +4. **Optional: Use Virtual Environment (Recommended):** + - If you prefer to install Bluepass within a **virtual environment**, set one up and activate it: + + python3 -m venv bluepass-env + source bluepass-env/bin/activate + +5. **Clone the Source Code:** + - Clone the Bluepass source from **GitHub**: + + git clone https://github.com/geertj/bluepass + +6. **Install Python Packages:** + - Inside the **Bluepass** directory, install the required Python packages: + + pip install -r requirements.txt + +7. **Install Bluepass:** + - Finally, install Bluepass by running: + + python setup.py install Installing on Ubuntu and Fedora =============================== -Ubuntu 13.04 and later, and Fedora 19 and later provide Python 3.3. On these -distributions it is recommended to use Python3 for running Bluepass. +For **Ubuntu 13.04** and later, and **Fedora 19** and later, **Python 3.3** is available through the distribution's package manager. It is recommended to use **Python 3** for running Bluepass on these platforms. + +Step 1: Install Dependencies +------------------------------- + +Both **Ubuntu** and **Fedora** provide most of the required dependencies, except for **Gruvi**. You can install the necessary dependencies using the following commands: + +On Ubuntu: + + sudo apt-get -y install gcc make python3-dev python3-pyqt4 python3-pip \ + libssl-dev libffi-dev git curl + +On Fedora: + + sudo yum -y install gcc make python3-devel python3-PyQt4 python3-pip \ + openssl-devel libffi-devel git curl + +Then run the following commands to install Bluepass from GitHub into a virtual environment. + + + + - pyvenv-3.3 --system-site-packages bluepass-dev + - source bluepass-dev/bin/activate + - curl -O https://pypi.python.org/packages/source/p/pip/pip-1.4.1.tar.gz + - tar xvfz pip-1.4.1.tar.gz + - pushd pip-1.4.1 + - python setup.py install + - popd + - git clone https://github.com/geertj/bluepass + - pushd bluepass + - pip install -r requirements.txt + - python setup.py install + +To run bluepass, use: + + bluepass + +On previous versions of Ubuntu and Fedora, use the generic installation instructions. + +Features +======== + +- **Secure Password Management**: Store and manage your passwords securely with state-of-the-art encryption techniques. +- **Peer-to-Peer Synchronization**: Sync your password database across multiple devices without relying on third-party cloud services, ensuring maximum privacy and control. +- **Open Source**: Contribute to and modify the source code as per your requirements, fostering a community-driven development approach. +- **Local Storage**: Keep your passwords stored locally on your device, enhancing security and reducing dependency on external services. + +Contributing +============ + +We welcome contributions from the community! If you're interested in helping improve Bluepass, please follow these guidelines: + +How to Contribute +----------------- + +1. **Fork the Repository**: Start by forking the `Bluepass GitHub repository ` to your own account. + +2. **Clone Your Fork**: Clone your forked repository to your local machine: + + git clone https://github.com/geertj/bluepass.git + +3. **Create a New Branch**: Create a new branch for your feature or bug fix: + + git checkout -b feature/your-feature-name + +4. **Make Your Changes**: Implement your feature, fix the bug, or improve the documentation as needed. -First you need to install dependencies. Apart from Gruvi, all dependencies are -provided by the distribution. On Ubuntu:: +5. **Write Tests**: If applicable, write tests for your changes to ensure everything works as expected. - $ sudo apt-get -y install gcc make python3-dev python3-pyqt4 python3-pip \ - libssl-dev libffi-dev git curl +6. **Commit Your Changes**: Commit your changes with a clear and descriptive commit message: -While on Fedora:: + git commit -m "Add feature: Your feature description" - $ sudo yum -y install gcc make python3-devel python3-PyQt4 python3-pip \ - openssl-devel libffi-devel git curl +7. **Push to Your Fork**: Push your changes back to your forked repository: -Then run the following commands. These commands install Bluepass from Github -into a virtualenv. Pip itself is installed from source because of -https://github.com/pypa/pip/issues/1408. :: + git push origin feature/your-feature-name - $ pyvenv-3.3 --system-site-packages bluepass-dev - $ . bluepass-dev/bin/activate - $ curl -O https://pypi.python.org/packages/source/p/pip/pip-1.4.1.tar.gz - $ tar xvfz pip-1.4.1.tar.gz && pushd pip-1.4.1 && python setup.py install && popd - $ git clone https://github.com/geertj/bluepass && pushd bluepass - $ pip install -r requirements.txt - $ python setup.py install +8. **Open a Pull Request**: Navigate to the original repository and open a pull request. Provide a detailed description of your changes, and reference any relevant issues. -To run bluepass, use "bluepass" from the command line. +Guidelines +---------- -On previous versions of Ubuntu and Fedora use the generic installation -instructions. +- **Code Style**: Follow the project's code style and conventions to maintain consistency. +- **Documentation**: If you add a new feature or change existing functionality, please update the documentation accordingly. +- **Issues**: If you encounter a bug or have a feature request, feel free to open an issue on the GitHub repository to discuss it with the maintainers.