mirror of
https://github.com/paperless-ngx/paperless-ngx.git
synced 2025-10-30 03:56:23 -05:00
Merge branch 'main' into dev
This commit is contained in:
Michael Shamoon
36
.github/PULL_REQUEST_TEMPLATE.md
vendored
Normal file
36
.github/PULL_REQUEST_TEMPLATE.md
vendored
Normal file
@@ -0,0 +1,36 @@
|
||||
## Proposed change
|
||||
|
||||
<!--
|
||||
Please include a summary of the change and which issue is fixed (if any) and any relevant motivation / context. List any dependencies that are required for this change. If appropriate, please include an explanation of how your poposed change can be tested. Screenshots and / or videos can also be helpful if appropriate.
|
||||
-->
|
||||
|
||||
Fixes # (issue)
|
||||
|
||||
<!--
|
||||
Please also tag the relevant team to help with review. You can tag any of the following:
|
||||
@paperless-ngx/backend (Python / django, database, etc.)
|
||||
@paperless-ngx/frontend (JavaScript/Typescript, HTML, CSS, etc.)
|
||||
@paperless-ngx/ci-cd (GitHub Actions, deployment)
|
||||
@paperless-ngx/test (General testing for larger PRs)
|
||||
-->
|
||||
|
||||
## Type of change
|
||||
|
||||
<!--
|
||||
What type of change does your PR introduce to Paperless-ngx?
|
||||
NOTE: Please check only one box!
|
||||
-->
|
||||
|
||||
- [ ] Bug fix (non-breaking change which fixes an issue)
|
||||
- [ ] New feature (non-breaking change which adds functionality)
|
||||
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
|
||||
- [ ] Other (please explain)
|
||||
|
||||
## Checklist:
|
||||
|
||||
- [ ] I have read & agree with the [contributing guidelines](https://github.com/paperless-ngx/paperless-ngx/blob/main/CONTRIBUTING.md).
|
||||
- [ ] If applicable, I have tested my code for new features & regressions on both mobile & desktop devices, using the latest version of major browsers.
|
||||
- [ ] If applicable, I have checked that all tests pass, see [documentation](https://paperless-ngx.readthedocs.io/en/latest/extending.html#back-end-development).
|
||||
- [ ] I have run all `pre-commit` hooks, see [documentation](https://paperless-ngx.readthedocs.io/en/latest/contributing.html#pre-commit-hooks).
|
||||
- [ ] I have made corresponding changes to the documentation as needed.
|
||||
- [ ] I have checked my modifications for any breaking changes.
|
||||
6
.github/dependabot.yml
vendored
6
.github/dependabot.yml
vendored
@@ -14,6 +14,9 @@ updates:
|
||||
labels:
|
||||
- "frontend"
|
||||
- "dependencies"
|
||||
# Add reviewers
|
||||
reviewers:
|
||||
- "paperless-ngx/frontend"
|
||||
|
||||
# Enable version updates for Python
|
||||
- package-ecosystem: "pip"
|
||||
@@ -36,3 +39,6 @@ updates:
|
||||
labels:
|
||||
- "ci-cd"
|
||||
- "dependencies"
|
||||
# Add reviewers
|
||||
reviewers:
|
||||
- "paperless-ngx/backend"
|
||||
|
||||
44
.github/workflows/project-actions.yml
vendored
Normal file
44
.github/workflows/project-actions.yml
vendored
Normal file
@@ -0,0 +1,44 @@
|
||||
name: Project automations
|
||||
on:
|
||||
issues:
|
||||
types:
|
||||
- opened
|
||||
- reopened
|
||||
pull_request:
|
||||
types:
|
||||
- opened
|
||||
- reopened
|
||||
|
||||
# map fields with customized labels
|
||||
env:
|
||||
todo: Todo
|
||||
done: Done
|
||||
in_progress: In Progress
|
||||
|
||||
jobs:
|
||||
issue_opened_or_reopened:
|
||||
name: issue_opened_or_reopened
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event_name == 'issues' && (github.event.action == 'opened' || github.event.action == 'reopened')
|
||||
steps:
|
||||
- name: Move issue to ${{ env.todo }}
|
||||
uses: leonsteinhaeuser/project-beta-automations@v1.2.1
|
||||
with:
|
||||
gh_token: ${{ secrets.GH_TOKEN }}
|
||||
organization: paperless-ngx
|
||||
project_id: 2
|
||||
resource_node_id: ${{ github.event.issue.node_id }}
|
||||
status_value: ${{ env.todo }} # Target status
|
||||
pr_opened_or_reopened_or_reviewrequested:
|
||||
name: pr_opened_or_reopened_or_reviewrequested
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event_name == 'pull_request' && (github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'review_requested')
|
||||
steps:
|
||||
- name: Move PR to ${{ env.in_progress }}
|
||||
uses: leonsteinhaeuser/project-beta-automations@v1.2.1
|
||||
with:
|
||||
gh_token: ${{ secrets.GH_TOKEN }}
|
||||
organization: paperless-ngx
|
||||
project_id: 2
|
||||
resource_node_id: ${{ github.event.pull_request.node_id }}
|
||||
status_value: ${{ env.in_progress }} # Target status
|
||||
128
CODE_OF_CONDUCT.md
Normal file
128
CODE_OF_CONDUCT.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# Contributor Covenant Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
We as members, contributors, and leaders pledge to make participation in our
|
||||
community a harassment-free experience for everyone, regardless of age, body
|
||||
size, visible or invisible disability, ethnicity, sex characteristics, gender
|
||||
identity and expression, level of experience, education, socio-economic status,
|
||||
nationality, personal appearance, race, religion, or sexual identity
|
||||
and orientation.
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming,
|
||||
diverse, inclusive, and healthy community.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to a positive environment for our
|
||||
community include:
|
||||
|
||||
* Demonstrating empathy and kindness toward other people
|
||||
* Being respectful of differing opinions, viewpoints, and experiences
|
||||
* Giving and gracefully accepting constructive feedback
|
||||
* Accepting responsibility and apologizing to those affected by our mistakes,
|
||||
and learning from the experience
|
||||
* Focusing on what is best not just for us as individuals, but for the
|
||||
overall community
|
||||
|
||||
Examples of unacceptable behavior include:
|
||||
|
||||
* The use of sexualized language or imagery, and sexual attention or
|
||||
advances of any kind
|
||||
* Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
* Public or private harassment
|
||||
* Publishing others' private information, such as a physical or email
|
||||
address, without their explicit permission
|
||||
* Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
|
||||
## Enforcement Responsibilities
|
||||
|
||||
Community leaders are responsible for clarifying and enforcing our standards of
|
||||
acceptable behavior and will take appropriate and fair corrective action in
|
||||
response to any behavior that they deem inappropriate, threatening, offensive,
|
||||
or harmful.
|
||||
|
||||
Community leaders have the right and responsibility to remove, edit, or reject
|
||||
comments, commits, code, wiki edits, issues, and other contributions that are
|
||||
not aligned to this Code of Conduct, and will communicate reasons for moderation
|
||||
decisions when appropriate.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies within all community spaces, and also applies when
|
||||
an individual is officially representing the community in public spaces.
|
||||
Examples of representing our community include using an official e-mail address,
|
||||
posting via an official social media account, or acting as an appointed
|
||||
representative at an online or offline event.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
||||
reported to the community leaders responsible for enforcement at
|
||||
hello@paperless-ngx.com.
|
||||
All complaints will be reviewed and investigated promptly and fairly.
|
||||
|
||||
All community leaders are obligated to respect the privacy and security of the
|
||||
reporter of any incident.
|
||||
|
||||
## Enforcement Guidelines
|
||||
|
||||
Community leaders will follow these Community Impact Guidelines in determining
|
||||
the consequences for any action they deem in violation of this Code of Conduct:
|
||||
|
||||
### 1. Correction
|
||||
|
||||
**Community Impact**: Use of inappropriate language or other behavior deemed
|
||||
unprofessional or unwelcome in the community.
|
||||
|
||||
**Consequence**: A private, written warning from community leaders, providing
|
||||
clarity around the nature of the violation and an explanation of why the
|
||||
behavior was inappropriate. A public apology may be requested.
|
||||
|
||||
### 2. Warning
|
||||
|
||||
**Community Impact**: A violation through a single incident or series
|
||||
of actions.
|
||||
|
||||
**Consequence**: A warning with consequences for continued behavior. No
|
||||
interaction with the people involved, including unsolicited interaction with
|
||||
those enforcing the Code of Conduct, for a specified period of time. This
|
||||
includes avoiding interactions in community spaces as well as external channels
|
||||
like social media. Violating these terms may lead to a temporary or
|
||||
permanent ban.
|
||||
|
||||
### 3. Temporary Ban
|
||||
|
||||
**Community Impact**: A serious violation of community standards, including
|
||||
sustained inappropriate behavior.
|
||||
|
||||
**Consequence**: A temporary ban from any sort of interaction or public
|
||||
communication with the community for a specified period of time. No public or
|
||||
private interaction with the people involved, including unsolicited interaction
|
||||
with those enforcing the Code of Conduct, is allowed during this period.
|
||||
Violating these terms may lead to a permanent ban.
|
||||
|
||||
### 4. Permanent Ban
|
||||
|
||||
**Community Impact**: Demonstrating a pattern of violation of community
|
||||
standards, including sustained inappropriate behavior, harassment of an
|
||||
individual, or aggression toward or disparagement of classes of individuals.
|
||||
|
||||
**Consequence**: A permanent ban from any sort of public interaction within
|
||||
the community.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
||||
version 2.0, available at
|
||||
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
|
||||
|
||||
Community Impact Guidelines were inspired by [Mozilla's code of conduct
|
||||
enforcement ladder](https://github.com/mozilla/diversity).
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
|
||||
For answers to common questions about this code of conduct, see the FAQ at
|
||||
https://www.contributor-covenant.org/faq. Translations are available at
|
||||
https://www.contributor-covenant.org/translations.
|
||||
@@ -15,7 +15,7 @@ Paperless supports python 3.8 and 3.9. We format Python code with [Black](https:
|
||||
|
||||
## Branches
|
||||
|
||||
`master` always reflects the latest release. Apart from changes to the documentation or readme, absolutely no functional changes on this branch in between releases.
|
||||
`main` always reflects the latest release. Apart from changes to the documentation or readme, absolutely no functional changes on this branch in between releases.
|
||||
|
||||
`dev` contains all changes that will be part of the next release. Use this branch to start making your changes.
|
||||
|
||||
@@ -95,3 +95,38 @@ Note that _en-us_ needs to stay on top of the list, as it is the default project
|
||||
|
||||
If you are familiar with Git, feel free to send a Pull Request with those changes.
|
||||
If not, let us know in the issue you created for the language, so that another developer can make these changes.
|
||||
|
||||
# Organization Structure & Membership
|
||||
|
||||
Paperless-ngx is a community project. We do our best to delegate permission and responsibility among a team of people to ensure the longevity of the project.
|
||||
|
||||
## Structure
|
||||
|
||||
As of writing, there are 21 members in paperless-ngx. 4 of these people have complete administrative privileges to the repo:
|
||||
|
||||
* [@shamoon](https://github.com/shamoon)
|
||||
* [@bauerj](https://github.com/bauerj)
|
||||
* [@qcasey](https://github.com/qcasey)
|
||||
* [@FrankStrieter](https://github.com/FrankStrieter)
|
||||
|
||||
There are 5 teams collaborating on specific tasks within paperless-ngx:
|
||||
|
||||
* @paperless-ngx/backend (Python / django)
|
||||
* @paperless-ngx/frontend (JavaScript / Typescript)
|
||||
* @paperless-ngx/ci-cd (GitHub Actions / Deployment)
|
||||
* @paperless-ngx/issues (Issue triage)
|
||||
* @paperless-ngx/test (General testing for larger PRs)
|
||||
|
||||
## Permissions
|
||||
|
||||
All team members are notified when mentioned or assigned to a relevant issue or pull request. Additionally, each team has slightly different access to paperless-ngx:
|
||||
|
||||
* The **test** team has no special permissions.
|
||||
* The **issues** team has `triage` access. This means they can organize issues and pull requests.
|
||||
* The **backend**, **frontend**, and **ci-cd** teams have `write` access. This means they can approve PRs and push code, containers, releases, and more.
|
||||
|
||||
## Joining
|
||||
|
||||
We are not overly strict with inviting people to the organization. If you have read the [team permissions](#permissions) and think having additional access would enhance your contributions, please reach out to an [admin](#structure) of the team.
|
||||
|
||||
The admins occasionally invite contributors directly if we believe having them on a team will accelerate their work.
|
||||
|
||||
@@ -52,8 +52,11 @@ Another big thanks to the people who have contributed translations:
|
||||
* Lars Sørensen (Lrss) suggested 167 translations into Danish.
|
||||
* Philmo67 suggested 11 translations into French.
|
||||
|
||||
Paperless-ng
|
||||
############
|
||||
|
||||
paperless-ng 1.5.0
|
||||
##################
|
||||
==================
|
||||
|
||||
Support for Python 3.6 was dropped.
|
||||
|
||||
@@ -64,7 +67,7 @@ Support for Python 3.6 was dropped.
|
||||
* `Daniel Albers`_ added support for making the files and folders ignored by the paperless consume folder scanner configurable. See ``PAPERLESS_CONSUMER_IGNORE_PATTERNS``.
|
||||
|
||||
paperless-ng 1.4.5
|
||||
##################
|
||||
==================
|
||||
|
||||
This is a maintenance release.
|
||||
|
||||
@@ -77,7 +80,7 @@ This is a maintenance release.
|
||||
with PDFminer even from non-PDF files.
|
||||
|
||||
paperless-ng 1.4.4
|
||||
##################
|
||||
==================
|
||||
|
||||
* Drastically decreased the startup time of the docker container. The startup script adjusts file permissions of all data only if changes are required.
|
||||
* Paperless mail: Added ability to specify the character set for each server.
|
||||
@@ -86,7 +89,7 @@ paperless-ng 1.4.4
|
||||
* Updated translations.
|
||||
|
||||
paperless-ng 1.4.3
|
||||
##################
|
||||
==================
|
||||
|
||||
* Additions and changes
|
||||
|
||||
@@ -103,12 +106,12 @@ paperless-ng 1.4.3
|
||||
* Fixed an issue with the document consumer crashing on certain documents due to issues with pdfminer.six. This library is used for PDF text extraction.
|
||||
|
||||
paperless-ng 1.4.2
|
||||
##################
|
||||
==================
|
||||
|
||||
* Fixed an issue with ``sudo`` that caused paperless to not start on many Raspberry Pi devices. Thank you `WhiteHatTux`_!
|
||||
|
||||
paperless-ng 1.4.1
|
||||
##################
|
||||
==================
|
||||
|
||||
* Added Polish locale.
|
||||
|
||||
@@ -124,7 +127,7 @@ paperless-ng 1.4.1
|
||||
``PAPERLESS_ADMIN_PASSWORD`` as environment variables to the docker container.
|
||||
|
||||
paperless-ng 1.4.0
|
||||
##################
|
||||
==================
|
||||
|
||||
* Docker images now use tesseract 4.1.1, which should fix a series of issues with OCR.
|
||||
|
||||
@@ -157,7 +160,7 @@ paperless-ng 1.4.0
|
||||
(see :ref:`administration-index`).
|
||||
|
||||
paperless-ng 1.3.2
|
||||
##################
|
||||
==================
|
||||
|
||||
* Added translation into Portuguese.
|
||||
|
||||
@@ -172,7 +175,7 @@ paperless-ng 1.3.2
|
||||
* Fixed an issue with any/all/exact matching when characters used in regular expressions were used for the match.
|
||||
|
||||
paperless-ng 1.3.1
|
||||
##################
|
||||
==================
|
||||
|
||||
* Added translation into Spanish and Russian.
|
||||
|
||||
@@ -197,7 +200,7 @@ paperless-ng 1.3.1
|
||||
* Fixed ``AUTO_LOGIN_USERNAME``: Unable to perform POST/PUT/DELETE requests and unable to receive WebSocket messages.
|
||||
|
||||
paperless-ng 1.3.0
|
||||
##################
|
||||
==================
|
||||
|
||||
This release contains new database migrations.
|
||||
|
||||
@@ -223,7 +226,7 @@ This release contains new database migrations.
|
||||
|
||||
|
||||
paperless-ng 1.2.1
|
||||
##################
|
||||
==================
|
||||
|
||||
* `Rodrigo Avelino <https://github.com/rodavelino>`_ translated Paperless into Portuguese (Brazil)!
|
||||
|
||||
@@ -236,7 +239,7 @@ paperless-ng 1.2.1
|
||||
* Regression fix: Dates on the front end did not respect date locale settings in some cases.
|
||||
|
||||
paperless-ng 1.2.0
|
||||
##################
|
||||
==================
|
||||
|
||||
* Changes to the OCRmyPDF integration
|
||||
|
||||
@@ -260,14 +263,14 @@ paperless-ng 1.2.0
|
||||
* Paperless no longer depends on ``libpoppler-cpp-dev``.
|
||||
|
||||
paperless-ng 1.1.4
|
||||
##################
|
||||
==================
|
||||
|
||||
* Added English (GB) locale.
|
||||
|
||||
* Added ISO-8601 date display option.
|
||||
|
||||
paperless-ng 1.1.3
|
||||
##################
|
||||
==================
|
||||
|
||||
* Added a docker-specific configuration option to adjust the number of
|
||||
worker processes of the web server. See :ref:`configuration-docker`.
|
||||
@@ -277,7 +280,7 @@ paperless-ng 1.1.3
|
||||
* Don't show inbox statistics if no inbox tag is defined.
|
||||
|
||||
paperless-ng 1.1.2
|
||||
##################
|
||||
==================
|
||||
|
||||
* Always show top left corner of thumbnails, even for extra wide documents.
|
||||
|
||||
@@ -293,7 +296,7 @@ paperless-ng 1.1.2
|
||||
* Some memory usage optimizations.
|
||||
|
||||
paperless-ng 1.1.1
|
||||
##################
|
||||
==================
|
||||
|
||||
This release contains new database migrations.
|
||||
|
||||
@@ -314,7 +317,7 @@ This release contains new database migrations.
|
||||
also ensure that they're always executed as the paperless user and you're less likely to run into permission issues. See :ref:`utilities-management-commands`.
|
||||
|
||||
paperless-ng 1.1.0
|
||||
##################
|
||||
==================
|
||||
|
||||
* Document processing status
|
||||
|
||||
@@ -374,7 +377,7 @@ paperless-ng 1.1.0
|
||||
``PAPERLESS_LOGROTATE_MAX_BACKUPS``.
|
||||
|
||||
paperless-ng 1.0.0
|
||||
##################
|
||||
==================
|
||||
|
||||
Nothing special about this release, but since there are relatively few bug reports coming in, I think that this is reasonably stable.
|
||||
|
||||
@@ -397,7 +400,7 @@ Nothing special about this release, but since there are relatively few bug repor
|
||||
|
||||
|
||||
paperless-ng 0.9.14
|
||||
###################
|
||||
===================
|
||||
|
||||
Starting with this version, releases are getting built automatically. This release also comes with changes on how to install and
|
||||
update paperless.
|
||||
@@ -445,13 +448,13 @@ update paperless.
|
||||
* An issue with the consumer crashing when invalid regular expression were used was fixed.
|
||||
|
||||
paperless-ng 0.9.13
|
||||
###################
|
||||
===================
|
||||
|
||||
* Fixed an issue with Paperless not starting due to the new Tika integration when ``USERMAP_UID`` and ``USERMAP_GID`` was used
|
||||
in the ``docker-compose.env`` file.
|
||||
|
||||
paperless-ng 0.9.12
|
||||
###################
|
||||
===================
|
||||
|
||||
* Paperless localization
|
||||
|
||||
@@ -493,13 +496,13 @@ paperless-ng 0.9.12
|
||||
a document that did not yet exist in the database.
|
||||
|
||||
paperless-ng 0.9.11
|
||||
###################
|
||||
===================
|
||||
|
||||
* Fixed an issue with the docker image not starting at all due to a configuration change of the web server.
|
||||
|
||||
|
||||
paperless-ng 0.9.10
|
||||
###################
|
||||
===================
|
||||
|
||||
* Bulk editing
|
||||
|
||||
@@ -532,7 +535,7 @@ paperless-ng 0.9.10
|
||||
by :ref:`running the management command document_index with the argument reindex <administration-index>`.
|
||||
|
||||
paperless-ng 0.9.9
|
||||
##################
|
||||
==================
|
||||
|
||||
Christmas release!
|
||||
|
||||
@@ -566,7 +569,7 @@ Christmas release!
|
||||
* Most of the guesswork features have been removed. Paperless no longer tries to extract correspondents and tags from file names.
|
||||
|
||||
paperless-ng 0.9.8
|
||||
##################
|
||||
==================
|
||||
|
||||
This release addresses two severe issues with the previous release.
|
||||
|
||||
@@ -575,7 +578,7 @@ This release addresses two severe issues with the previous release.
|
||||
|
||||
|
||||
paperless-ng 0.9.7
|
||||
##################
|
||||
==================
|
||||
|
||||
|
||||
* Front end
|
||||
@@ -617,7 +620,7 @@ paperless-ng 0.9.7
|
||||
|
||||
|
||||
paperless-ng 0.9.6
|
||||
##################
|
||||
==================
|
||||
|
||||
This release focusses primarily on many small issues with the UI.
|
||||
|
||||
@@ -658,7 +661,7 @@ This release focusses primarily on many small issues with the UI.
|
||||
|
||||
|
||||
paperless-ng 0.9.5
|
||||
##################
|
||||
==================
|
||||
|
||||
This release concludes the big changes I wanted to get rolled into paperless. The next releases before 1.0 will
|
||||
focus on fixing issues, primarily.
|
||||
@@ -708,7 +711,7 @@ focus on fixing issues, primarily.
|
||||
* Assigning correspondents from mail sender names failed for very long names. Paperless no longer assigns correspondents in these cases.
|
||||
|
||||
paperless-ng 0.9.4
|
||||
##################
|
||||
==================
|
||||
|
||||
* Searching:
|
||||
|
||||
@@ -736,7 +739,7 @@ paperless-ng 0.9.4
|
||||
how to setup the development environment.
|
||||
|
||||
paperless-ng 0.9.3
|
||||
##################
|
||||
==================
|
||||
|
||||
* Setting ``PAPERLESS_AUTO_LOGIN_USERNAME`` replaces ``PAPERLESS_DISABLE_LOGIN``.
|
||||
You have to specify your username.
|
||||
@@ -754,7 +757,7 @@ paperless-ng 0.9.3
|
||||
* Added lots of tests for various parts of the application.
|
||||
|
||||
paperless-ng 0.9.2
|
||||
##################
|
||||
==================
|
||||
|
||||
* Major changes to the front end (colors, logo, shadows, layout of the cards,
|
||||
better mobile support)
|
||||
@@ -784,7 +787,7 @@ paperless-ng 0.9.2
|
||||
up in the admin.
|
||||
|
||||
paperless-ng 0.9.1
|
||||
##################
|
||||
==================
|
||||
|
||||
* Moved documentation of the settings to the actual documentation.
|
||||
* Updated release script to force the user to choose between SQLite
|
||||
@@ -792,7 +795,7 @@ paperless-ng 0.9.1
|
||||
|
||||
|
||||
paperless-ng 0.9.0
|
||||
##################
|
||||
==================
|
||||
|
||||
* **Deprecated:** GnuPG. :ref:`See this note on the state of GnuPG in paperless-ng. <utilities-encyption>`
|
||||
This features will most likely be removed in future versions.
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
.. _contributing:
|
||||
|
||||
Contributing to Paperless
|
||||
#########################
|
||||
|
||||
.. warning::
|
||||
|
||||
This section is not updated to paperless-ngx yet.
|
||||
|
||||
Maybe you've been using Paperless for a while and want to add a feature or two,
|
||||
or maybe you've come across a bug that you have some ideas how to solve. The
|
||||
beauty of Free software is that you can see what's wrong and help to get it
|
||||
fixed for everyone!
|
||||
|
||||
|
||||
How to Get Your Changes Rolled Into Paperless
|
||||
=============================================
|
||||
|
||||
If you've found a bug, but don't know how to fix it, you can always post an
|
||||
issue on `GitHub`_ in the hopes that someone will have the time to fix it for
|
||||
you. If however you're the one with the time, pull requests are always
|
||||
welcome, you just have to make sure that your code conforms to a few standards.
|
||||
|
||||
pre-commit Hooks
|
||||
-----------------------
|
||||
|
||||
To ensure a consistent style and formatting across the project source, the project
|
||||
utilizes a Git `pre-commit` hook to preform some formatting and linting before a
|
||||
commit is allowed. That way, everyone uses the same style and some common issues
|
||||
can be caught early on.
|
||||
|
||||
The first time you are setting up to contribute, you'll need to install this hook.
|
||||
If you've followed the initial development setup instructions, just run the following:
|
||||
|
||||
.. code:: shell-session
|
||||
|
||||
pre-commit install
|
||||
|
||||
That's it! The hooks will now run when you commit. If the formatting isn't quite right
|
||||
or a linter catches something, the commit will be rejected. You'll need to look at the
|
||||
output and fix the issue. Some hooks, such as the Python formatting tool `black`
|
||||
will format failing files, so all you need to do is `git add` those files again and retry your
|
||||
commit.
|
||||
|
||||
|
||||
The Code of Conduct
|
||||
===================
|
||||
|
||||
Paperless has a `code of conduct`_. It's a lot like the other ones you see out
|
||||
there, with a few small changes, but basically it boils down to:
|
||||
|
||||
> Don't be an ass, or you might get banned.
|
||||
|
||||
I'm proud to say that the CoC has never had to be enforced because everyone has
|
||||
been awesome, friendly, and professional.
|
||||
|
||||
.. _GitHub: https://github.com/the-paperless-project/paperless/issues
|
||||
.. _code of conduct: https://github.com/the-paperless-project/paperless/blob/master/CODE_OF_CONDUCT.md
|
||||
@@ -1,13 +1,13 @@
|
||||
.. _extending:
|
||||
|
||||
Paperless development
|
||||
#####################
|
||||
Paperless-ngx Development
|
||||
#########################
|
||||
|
||||
This section describes the steps you need to take to start development on paperless-ngx.
|
||||
|
||||
Check out the source from github. The repository is organized in the following way:
|
||||
|
||||
* ``master`` always represents the latest release and will only see changes
|
||||
* ``main`` always represents the latest release and will only see changes
|
||||
when a new release is made.
|
||||
* ``dev`` contains the code that will be in the next release.
|
||||
* ``feature-X`` contain bigger changes that will be in some release, but not
|
||||
@@ -23,6 +23,31 @@ Apart from that, the folder structure is as follows:
|
||||
* ``scripts/`` - Various scripts that help with different parts of development.
|
||||
* ``docker/`` - Files required to build the docker image.
|
||||
|
||||
Contributing to Paperless
|
||||
=========================
|
||||
|
||||
Maybe you've been using Paperless for a while and want to add a feature or two,
|
||||
or maybe you've come across a bug that you have some ideas how to solve. The
|
||||
beauty of open source software is that you can see what's wrong and help to get
|
||||
it fixed for everyone!
|
||||
|
||||
Before contributing please review our `code of conduct`_ and other important
|
||||
information in the `contributing guidelines`_.
|
||||
|
||||
Code formatting with pre-commit Hooks
|
||||
=====================================
|
||||
|
||||
To ensure a consistent style and formatting across the project source, the project
|
||||
utilizes a Git `pre-commit` hook to perform some formatting and linting before a
|
||||
commit is allowed. That way, everyone uses the same style and some common issues
|
||||
can be caught early on. See below for installation instructions.
|
||||
|
||||
Once installed, hooks will run when you commit. If the formatting isn't quite right
|
||||
or a linter catches something, the commit will be rejected. You'll need to look at the
|
||||
output and fix the issue. Some hooks, such as the Python formatting tool `black`,
|
||||
will format failing files, so all you need to do is `git add` those files again and
|
||||
retry your commit.
|
||||
|
||||
Initial setup and first start
|
||||
=============================
|
||||
|
||||
@@ -37,13 +62,19 @@ To do the setup you need to perform the steps from the following chapters in a c
|
||||
|
||||
$ npm install -g @angular/cli
|
||||
|
||||
4. Create ``consume`` and ``media`` folders in the cloned root folder.
|
||||
4. Install pre-commit
|
||||
|
||||
.. code:: shell-session
|
||||
|
||||
pre-commit install
|
||||
|
||||
5. Create ``consume`` and ``media`` folders in the cloned root folder.
|
||||
|
||||
.. code:: shell-session
|
||||
|
||||
mkdir -p consume media
|
||||
|
||||
5. You can now either ...
|
||||
6. You can now either ...
|
||||
|
||||
* install redis or
|
||||
* use the included scripts/start-services.sh to use docker to fire up a redis instance (and some other services such as tika, gotenberg and a postgresql server) or
|
||||
@@ -53,18 +84,13 @@ To do the setup you need to perform the steps from the following chapters in a c
|
||||
|
||||
docker run -d -p 6379:6379 --restart unless-stopped redis:latest
|
||||
|
||||
6. Install the python dependencies by performing in the src/ directory.
|
||||
7. Install the python dependencies by performing in the src/ directory.
|
||||
.. code:: shell-session
|
||||
|
||||
pipenv install --dev
|
||||
|
||||
* Make sure you're using python 3.9.x or lower. Otherwise you might get issues with building dependencies. You can use `pyenv <https://github.com/pyenv/pyenv>`_ to install a specific python version.
|
||||
|
||||
7. Install the Git hooks
|
||||
.. code:: shell-session
|
||||
|
||||
pre-commit install
|
||||
|
||||
8. Generate the static UI so you can perform a login to get session that is required for frontend development (this needs to be done one time only). From src-ui directory:
|
||||
|
||||
.. code:: shell-session
|
||||
@@ -92,7 +118,7 @@ Backend development environment is now ready, to start Frontend development go t
|
||||
Back end development
|
||||
====================
|
||||
|
||||
The backend is a django application. I use PyCharm for development, but you can use whatever
|
||||
The backend is a django application. PyCharm works well for development, but you can use whatever
|
||||
you want.
|
||||
|
||||
Configure the IDE to use the src/ folder as the base source folder. Configure the following
|
||||
@@ -127,9 +153,8 @@ Testing and code style:
|
||||
Front end development
|
||||
=====================
|
||||
|
||||
The front end is build using angular. I use the ``Code - OSS`` IDE for development.
|
||||
|
||||
In order to get started, you need ``npm``. Install the Angular CLI interface with
|
||||
The front end is built using Angular. In order to get started, you need ``npm``.
|
||||
Install the Angular CLI interface with
|
||||
|
||||
.. code:: shell-session
|
||||
|
||||
@@ -367,3 +392,6 @@ that returns information about your parser:
|
||||
download. We could guess that from the file extensions, but some mime types have many extensions
|
||||
associated with them and the python methods responsible for guessing the extension do not always
|
||||
return the same value.
|
||||
|
||||
.. _code of conduct: https://github.com/paperless-ngx/paperless-ngx/blob/main/CODE_OF_CONDUCT.md
|
||||
.. _contributing guidelines: https://github.com/paperless-ngx/paperless-ngx/blob/main/CONTRIBUTING.md
|
||||
|
||||
@@ -70,7 +70,6 @@ Contents
|
||||
faq
|
||||
troubleshooting
|
||||
extending
|
||||
contributing
|
||||
scanners
|
||||
screenshots
|
||||
changelog
|
||||
|
||||
@@ -1 +1 @@
|
||||
__version__ = (1, 5, 0)
|
||||
__version__ = (1, 6, 0)
|
||||
|
||||
Reference in New Issue
Block a user