diff --git a/.dockerignore b/.dockerignore
index 9978ae96e..21bb87de4 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -5,4 +5,4 @@ tests/
*.txt
!/requirements.txt
venv/
-
+devel/
\ No newline at end of file
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 000000000..76001ae9a
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -0,0 +1,11 @@
+### REPOSITORY
+/.github/CODEOWNERS @sdushantha
+/LICENSE @sdushantha
+
+### PACKAGING
+# Changes made to these items without code owner approval may negatively
+# impact packaging pipelines. Code owners may need time to verify or adapt.
+/pyproject.toml @ppfeister @sdushantha
+/setup.cfg @ppfeister @sdushantha
+/setup.py @ppfeister
+/*.spec @ppfeister
diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md
deleted file mode 100644
index f7f9b8227..000000000
--- a/.github/ISSUE_TEMPLATE/bug-report.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-name: Bug report
-about: Report a bug in Sherlock's functionality
-title: ''
-labels: bug
-assignees: ''
-
----
-
-
-
-
-## Checklist
-
-
-- [ ] I'm reporting a bug in Sherlock's functionality
-- [ ] The bug I'm reporting is not a false positive or a false negative
-- [ ] I've verified that I'm running the latest version of Sherlock
-- [ ] I've checked for similar bug reports including closed ones
-- [ ] I've checked for pull requests that attempt to fix this bug
-
-## Description
-
-
-WRITE DESCRIPTION HERE
diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml
new file mode 100644
index 000000000..9dd716553
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -0,0 +1,57 @@
+name: Bug Report
+description: File a bug report
+labels: ["bug"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for taking the time to fill out this bug report!
+ - type: textarea
+ id: description
+ attributes:
+ label: Description
+ description: Describe the bug you are experiencing
+ placeholder: Something happend when I did something
+ validations:
+ required: true
+ - type: textarea
+ id: steps-to-reproduce
+ attributes:
+ label: Steps to reproduce
+ description: Write a step by step list that will allow us to reproduce this bug
+ placeholder: |
+ 1. Do something
+ 2. Then do something else
+ validations:
+ required: true
+ - type: textarea
+ id: expected-behavior
+ attributes:
+ label: Expected behavior
+ description: Explain how you expect Sherlock to behave
+ placeholder: I expect Sherlock to behave like this when that is done
+ validations:
+ required: true
+ - type: textarea
+ id: actual-behavior
+ attributes:
+ label: Actual behavior
+ description: Explain how Sherlock is acutally behaving
+ placeholder: Sherlock should be behaving like this when that is done
+ validations:
+ required: true
+ - type: textarea
+ id: additional-info
+ attributes:
+ label: Additional information
+ description: If you have some additional information, please write it here
+ validations:
+ required: true
+ - type: checkboxes
+ id: terms
+ attributes:
+ label: Code of Conduct
+ description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/sherlock-project/sherlock/blob/master/docs/CODE_OF_CONDUCT.md).
+ options:
+ - label: I agree to follow this project's Code of Conduct
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 000000000..3ba13e0ce
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1 @@
+blank_issues_enabled: false
diff --git a/.github/ISSUE_TEMPLATE/false-negative.yml b/.github/ISSUE_TEMPLATE/false-negative.yml
new file mode 100644
index 000000000..03d212293
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/false-negative.yml
@@ -0,0 +1,20 @@
+name: False Negative
+description: Report a site that is returning false negative results
+labels: ["false negative"]
+body:
+ - type: input
+ id: site-name
+ attributes:
+ label: Site name
+ description: What site is returning false negatives?
+ placeholder: Reddit
+ validations:
+ required: True
+ - type: textarea
+ id: additional-info
+ attributes:
+ label: Additional info
+ description: If you know why the site is returning false negatives, please explain
+ placeholder: Reddit is returning false negatives because...
+ validations:
+ required: false
diff --git a/.github/ISSUE_TEMPLATE/false-positive.yml b/.github/ISSUE_TEMPLATE/false-positive.yml
new file mode 100644
index 000000000..e8bc4587c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/false-positive.yml
@@ -0,0 +1,20 @@
+name: Flase Positive
+description: Report a site that is returning false positive results
+labels: ["false positive"]
+body:
+ - type: input
+ id: site-name
+ attributes:
+ label: Site name
+ description: What site is returning false positives?
+ placeholder: Reddit
+ validations:
+ required: True
+ - type: textarea
+ id: additional-info
+ attributes:
+ label: Additional info
+ description: If you know why the site is returning false positives, please explain
+ placeholder: Reddit is returning false positives because...
+ validations:
+ required: false
diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md
deleted file mode 100644
index 67ec7ecf0..000000000
--- a/.github/ISSUE_TEMPLATE/feature-request.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-name: Feature request
-about: Request a new functionality for Sherlock
-title: ''
-labels: enhancement
-assignees: ''
-
----
-
-
-
-## Checklist
-
-- [ ] I'm reporting a feature request
-- [ ] I've checked for similar feature requests including closed ones
-
-## Description
-
-
-WRITE DESCRIPTION HERE
diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml
new file mode 100644
index 000000000..654ac7dc1
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature-request.yml
@@ -0,0 +1,12 @@
+name: Feature Request
+description: Request a feature
+labels: ["enhancement"]
+body:
+ - type: textarea
+ id: description
+ attributes:
+ label: Description
+ description: Describe the feature you are requesting
+ placeholder: I'd like Sherlock to be able to do xyz
+ validations:
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md
deleted file mode 100644
index 07cc2eec5..000000000
--- a/.github/ISSUE_TEMPLATE/question.md
+++ /dev/null
@@ -1,33 +0,0 @@
----
-name: Question
-about: Ask us a question
-title: ''
-labels: question
-assignees: ''
-
----
-
-
-
-## Checklist
-
-- [ ] I'm asking a question regarding Sherlock
-- [ ] My question is not a tech support question.
-
-**We are not your tech support**.
-If you have questions related to `pip`, `git`, or something that is not related to Sherlock, please ask them on [Stack Overflow](https://stackoverflow.com/) or [r/learnpython](https://www.reddit.com/r/learnpython/)
-
-
-## Question
-
-ASK YOUR QUESTION HERE
diff --git a/.github/ISSUE_TEMPLATE/reporting-false-negative.md b/.github/ISSUE_TEMPLATE/reporting-false-negative.md
deleted file mode 100644
index d511c5f86..000000000
--- a/.github/ISSUE_TEMPLATE/reporting-false-negative.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-name: Reporting false negative
-about: Reporting a site that is returning false positives
-title: ''
-labels: false negative
-assignees: ''
-
----
-
-
-
-## Checklist
-
-- [ ] I'm reporting a website that is returning **false negative** results
-- [ ] I've checked for similar site support requests including closed ones
-- [ ] I've checked for pull requests attempting to fix this false negative
-- [ ] I'm only reporting **one** site (create a separate issue for each site)
-
-## Description
-
-
-WRITE DESCRIPTION HERE
diff --git a/.github/ISSUE_TEMPLATE/reporting-false-positive.md b/.github/ISSUE_TEMPLATE/reporting-false-positive.md
deleted file mode 100644
index 7f968b5e6..000000000
--- a/.github/ISSUE_TEMPLATE/reporting-false-positive.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-name: Reporting false positive
-about: Reporting a site that is returning false positives
-title: ''
-labels: false positive
-assignees: ''
-
----
-
-
-
-## Checklist
-
-- [ ] I'm reporting a website that is returning **false positive** results
-- [ ] I've checked for similar site support requests including closed ones
-- [ ] I've checked for pull requests attempting to fix this false positive
-- [ ] I'm only reporting **one** site (create a separate issue for each site)
-
-## Description
-
-
-WRITE DESCRIPTION HERE
diff --git a/.github/ISSUE_TEMPLATE/site-request.yml b/.github/ISSUE_TEMPLATE/site-request.yml
new file mode 100644
index 000000000..86d7b169b
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/site-request.yml
@@ -0,0 +1,20 @@
+name: Site Support
+description: Request a site Sherlock should support
+labels: ["site support request"]
+body:
+ - type: input
+ id: site-name
+ attributes:
+ label: Site name
+ description: What site should Sherlock support?
+ placeholder: Reddit
+ validations:
+ required: True
+ - type: textarea
+ id: additional-info
+ attributes:
+ label: Additional info
+ description: If you have suggestions on how Sherlock should detect for usernames, please explain below
+ placeholder: Sherlock can detect if a username exists on Reddit by checking for...
+ validations:
+ required: false
diff --git a/.github/ISSUE_TEMPLATE/site-support-request.md b/.github/ISSUE_TEMPLATE/site-support-request.md
deleted file mode 100644
index 3810c55d6..000000000
--- a/.github/ISSUE_TEMPLATE/site-support-request.md
+++ /dev/null
@@ -1,37 +0,0 @@
----
-name: Site support request
-about: Request support for a new site
-title: ''
-labels: site support request
-assignees: ''
-
----
-
-
-
-## Checklist
-
-
-- [ ] I'm requesting support for a new site
-- [ ] I've checked for similar site support requests including closed ones
-- [ ] I've checked that the site I am requesting has not been removed in the past and is not documented in [removed_sites.md](https://github.com/sherlock-project/sherlock/blob/master/removed_sites.md)
-- [ ] The site I am requesting support for is not a pornographic website
-- [ ] I'm only requesting support of **one** website (create a separate issue for each site)
-
-## Description
-
-
-URL:
diff --git a/.github/workflows/update-site-list.yml b/.github/workflows/update-site-list.yml
index 1966beab2..5a0679332 100644
--- a/.github/workflows/update-site-list.yml
+++ b/.github/workflows/update-site-list.yml
@@ -29,8 +29,8 @@ jobs:
python-version: '3.x'
# Execute the site_list.py Python script
- - name: Execute site_list.py
- run: python site_list.py
+ - name: Execute site-list.py
+ run: python devel/site-list.py
# Commit any changes made by the script
- name: Commit files
diff --git a/.gitignore b/.gitignore
index 0552d4171..4d47421ae 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,6 +14,9 @@ __pycache__/
# Pip
src/
+# Pip / PyProject Devel & Installation
+*.egg-info/
+
# Jupyter Notebook
.ipynb_checkpoints
*.ipynb
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644
index 7a2fa3fe9..000000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# How To Contribute To Sherlock
-First off, thank you for the help!
-
-There are many ways to contribute. Here is some high level grouping.
-
-## Adding New Sites
-
-Please look at the Wiki entry on
-[adding new sites](https://github.com/sherlock-project/sherlock/wiki/Adding-Sites-To-Sherlock)
-to understand the issues.
-
-Any new sites that are added need to have a username that has been claimed, and one
-that is unclaimed documented in the site data. This allows the regression tests
-to ensure that everything is working.
-
-It is required that a contributor test any new sites by either running the full tests, or running
-a site-specific query against the claimed and unclaimed usernames.
-
-It is not required that a contributor run the
-[site_list.py](https://github.com/sherlock-project/sherlock/blob/master/site_list.py)
-script.
-
-If there are performance problems with a site (e.g. slow to respond, unreliable uptime, ...), then
-the site may be removed from the list. The
-[removed_sites.md](https://github.com/sherlock-project/sherlock/blob/master/removed_sites.md)
-file contains sites that were included at one time in Sherlock, but had to be removed for
-one reason or another.
-
-## Adding New Functionality
-
-Please ensure that the content on your branch passes all tests before submitting a pull request.
diff --git a/Dockerfile b/Dockerfile
index 4bbdd871c..ca2db2ec7 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -18,9 +18,9 @@ LABEL org.label-schema.vcs-ref=$VCS_REF \
COPY --from=build /wheels /wheels
COPY . /opt/sherlock/
-RUN pip3 install --no-cache-dir -r requirements.txt -f /wheels \
+RUN pip3 install --no-cache-dir . -f /wheels \
&& rm -rf /wheels
WORKDIR /opt/sherlock/sherlock
-ENTRYPOINT ["python", "sherlock.py"]
+ENTRYPOINT ["sherlock"]
diff --git a/site_list.py b/devel/site-list.py
similarity index 85%
rename from site_list.py
rename to devel/site-list.py
index 1f0f05fd4..1b4a03cfb 100644
--- a/site_list.py
+++ b/devel/site-list.py
@@ -4,7 +4,7 @@
import json
# Read the data.json file
-with open("sherlock/resources/data.json", "r", encoding="utf-8") as data_file:
+with open("../sherlock/resources/data.json", "r", encoding="utf-8") as data_file:
data: dict = json.load(data_file)
# Removes schema-specific keywords for proper processing
@@ -15,7 +15,7 @@
social_networks: list = sorted(social_networks.items())
# Write the list of supported sites to sites.md
-with open("sites.md", "w") as site_file:
+with open("../sites.md", "w") as site_file:
site_file.write(f"## List Of Supported Sites ({len(social_networks)} Sites In Total!)\n")
for social_network, info in social_networks:
url_main = info["urlMain"]
@@ -23,7 +23,7 @@
site_file.write(f"1. ![](https://www.google.com/s2/favicons?domain={url_main}) [{social_network}]({url_main}) {is_nsfw}\n")
# Overwrite the data.json file with sorted data
-with open("sherlock/resources/data.json", "w") as data_file:
+with open("../sherlock/resources/data.json", "w") as data_file:
sorted_data = json.dumps(data, indent=2, sort_keys=True)
data_file.write(sorted_data)
data_file.write("\n")
diff --git a/docker-compose.yml b/docker-compose.yml
deleted file mode 100644
index 3182120e8..000000000
--- a/docker-compose.yml
+++ /dev/null
@@ -1,7 +0,0 @@
-version: '2'
-
-services:
- sherlock:
- build: .
- volumes:
- - "./results:/opt/sherlock/results"
diff --git a/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md
similarity index 100%
rename from CODE_OF_CONDUCT.md
rename to docs/CODE_OF_CONDUCT.md
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 000000000..996efe8a3
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,88 @@
+
+
+# How to contribute to Sherlock
+
+We would love to have you help us with the development of Sherlock. Each and every contribution is greatly valued!
+
+Here are some things we would appreciate your help on:
+1. [Adding targets](#adding-targets)
+1. [Cleaning up existing targets](#removing-targets)
+1. [Restoring previously removed targets](#restoring-targets)
+
+## Adding targets
+
+Please look at the Wiki entry on [adding new sites][wiki_new_sites] to understand the issues.
+
+All new sites that are added to Sherlock need to have an existing (already claimed) username included in their definition. The linked Wiki page describes this in more detail. This inclusion allows us to run unit tests and prevent regression.
+
+Contributors are *required* to test any new sites for both false positives and false negatives. Contributors are *encouraged* to run unit tests as well.
+
+Contributors do not have to run the [site_list.py](/site_list.py) script, as it's ran automagically on master after each manifest change.
+
+## Removing targets
+
+If there are performance problems with a site (e.g. slow to respond, unreliable uptime, ...), then
+the site may be removed from the list. The [removed_sites.md][file_removed_md] file contains sites that were included at one time in Sherlock, but had to be removed for one reason or another.
+
+If a site has *occasional* performance problems, but is otherwise accurate, it may be preferable to add a test to weed out false positives rather than removing it.
+
+## Restoring targets
+
+Likely our biggest backlog. If you can propose a functional query that complies with [#Adding targets](#adding-targets) that would shrink our [removed sites list][file_removed_md], that would be greatly appreciated.
+
+## Adding New Functionality
+
+Contributors that would like to add a feature to Sherlock should open an new [issue][issues_new], proposing their idea. Indicate that you would like to make a Pull Request for said feature.
+
+Creating an Issue prior to opening a PR helps with tracking, discussions, and avoids hurt feelings if for whatever reason we don't feel that a feature is compatible with the project.
+
+Please ensure that the content on your branch passes all tests before submitting a pull request.
+
+# Coverage and Unit Tests
+
+Thank you for contributing to Sherlock!
+
+Before creating a pull request with new development, please run the tests
+to ensure that everything is working great. It would also be a good idea to run the tests
+before starting development to distinguish problems between your
+environment and the Sherlock software.
+
+The following is an example of the command line to run all the tests for
+Sherlock. This invocation hides the progress text that Sherlock normally
+outputs, and instead shows the verbose output of the tests.
+
+```console
+$ cd sherlock/sherlock
+$ python3 -m unittest tests.all --verbose
+```
+
+Unfortunately, some of the sites that Sherlock checks are not always reliable, so it is common
+to get response problems. Any problems in connection will show up as warnings in the tests instead of true errors.
+
+If some sites are failing due to connection problems (site is down, in maintenance, etc) you can exclude them from tests by creating a `tests/.excluded_sites` file with a list of sites to ignore (one site name per line).
+
+## Coverage for new features
+
+Contributors that add new features are *encouraged* make an attempt at creating unit tests for them, as well. Not all contributions are suitable for unit tests, but when it's doable, it helps prevent regression.
+
+
+
+[wiki_new_sites]: https://github.com/sherlock-project/sherlock/wiki/Adding-Sites-To-Sherlock
+[file_removed_md]: /removed_sites.md
+[issues_new]: https://github.com/sherlock-project/sherlock/issues/new/choose
\ No newline at end of file
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
new file mode 100644
index 000000000..9813a09c0
--- /dev/null
+++ b/docs/INSTALL.md
@@ -0,0 +1,95 @@
+
+
+```bash
+# pipx is recommended, but pip may suffice if pipx is unavailable
+pipx install sherlock-project
+```
+
+### Build python package from source (useful for contributors)
+
+```bash
+# pipx is recommended, but pip may suffice if pipx is unavailable
+git clone https://github.com/sherlock-project/sherlock.git
+cd sherlock
+pipx install .
+```
+
+
+Docker
+
+
+
+> [!NOTE]
+> Sherlock doesn't yet have context detection. It's recommended that Docker containers be ran with option `-o /opt/sherlock/results/{user123}.txt` (replace {user123}) when an output file is desired at the mounted volume (as seen in the compose).
+>
+> This has no effect on stdout, which functions as expected out of the box.
+
+```bash
+# One-off searches
+docker run --rm -t sherlock/sherlock user123
+
+# If you need to save the output file... (modify as needed)
+# Output file will land in ${pwd}/results
+docker run --rm -t -v "$PWD/results:/opt/sherlock/results" sherlock/sherlock -o /opt/sherlock/results/text.txt user123
+```
+
+```bash
+# At any time, you may update the image via this command
+docker pull sherlock/sherlock
+```
+
+### Using compose
+
+```yml
+version: "3"
+services:
+ sherlock:
+ container_name: sherlock
+ image: sherlock/sherlock
+ volumes:
+ - ./sherlock/:/opt/sherlock/results/
+```
+
+```bash
+docker compose run sherlock user123
+```
+
+### Build image from source (useful for contributors)
+
+```bash
+# Assumes ${pwd} is repository root
+docker build -t sherlock .
+docker run --rm -t sherlock user123
+```
diff --git a/README.md b/docs/README.md
similarity index 57%
rename from README.md
rename to docs/README.md
index f8b1c0290..9df30261d 100644
--- a/README.md
+++ b/docs/README.md
@@ -2,18 +2,18 @@
- Hunt down social media accounts by username across social networks
+ Hunt down social media accounts by username across 400+ social networks