Please read and understand the contribution guide before creating an issue or pull request.
## Etiquette
The guide can be found here: [https://docs.pi-hole.net/guides/github/contributing/](https://docs.pi-hole.net/guides/github/contributing/)
- Our goal for Pi-hole is **stability before features**. This means we focus on squashing critical bugs before adding new features. Often, we can do both in tandem, but bugs will take priority over a new feature.
- Pi-hole is open source and [powered by donations](https://pi-hole.net/donate/), and as such, we give our **free time** to build, maintain, and **provide user support** for this project. It would be extremely unfair for us to suffer abuse or anger for our hard work, so please take a moment to consider that.
- Please be considerate towards the developers and other users when raising issues or presenting pull requests.
- Respect our decision(s), and do not be upset or abusive if your submission is not used.
## Viability
When requesting or submitting new features, first consider whether it might be useful to others. Open source projects are used by many people, who may have entirely different needs to your own. Think about whether or not your feature is likely to be used by other users of the project.
## Procedure
**Before filing an issue:**
- Attempt to replicate and **document** the problem, to ensure that it wasn't a coincidental incident.
- Check to make sure your feature suggestion isn't already present within the project.
- Check the pull requests tab to ensure that the bug doesn't have a fix in progress.
- Check the pull requests tab to ensure that the feature isn't already in progress.
**Before submitting a pull request:**
- Check the codebase to ensure that your feature doesn't already exist.
- Check the pull requests to ensure that another person hasn't already submitted the feature or fix.
- Read and understand the [DCO guidelines](https://docs.pi-hole.net/guides/github/contributing/) for the project.
## Technical Requirements
- Submit Pull Requests to the **development branch only**.
- Before Submitting your Pull Request, merge `development` with your new branch and fix any conflicts. (Make sure you don't break anything in development!)
- Please use the [Google Style Guide for Shell](https://google.github.io/styleguide/shell.xml) for your code submission styles.
- Commit Unix line endings.
- Please use the Pi-hole brand: **Pi-hole** (Take a special look at the capitalized 'P' and a low 'h' with a hyphen)
- (Optional fun) keep to the theme of Star Trek/black holes/gravity.
## Forking and Cloning from GitHub to GitHub
1. Fork <https://github.com/pi-hole/pi-hole/> to a repo under a namespace you control, or have permission to use, for example: `https://github.com/<your_namespace>/<your_repo_name>/`. You can do this from the github.com website.
2. Clone `https://github.com/<your_namespace>/<your_repo_name>/` with the tool of you choice.
3. To keep your fork in sync with our repo, add an upstream remote for pi-hole/pi-hole to your repo.
4. Checkout the `development` branch from your fork `https://github.com/<your_namespace>/<your_repo_name>/`.
5. Create a topic/branch, based on the `development` branch code. *Bonus fun to keep to the theme of Star Trek/black holes/gravity.*
6. Make your changes and commit to your topic branch in your repo.
7. Rebase your commits and squash any insignificant commits. See the notes below for an example.
8. Merge `development` your branch and fix any conflicts.
9. Open a Pull Request to merge your topic branch into our repo's `development` branch.
- Keep in mind the technical requirements from above.
## Forking and Cloning from GitHub to other code hosting sites
- Forking is a GitHub concept and cannot be done from GitHub to other git-based code hosting sites. However, those sites may be able to mirror a GitHub repo.
1. To contribute from another code hosting site, you must first complete the steps above to fork our repo to a GitHub namespace you have permission to use, for example: `https://github.com/<your_namespace>/<your_repo_name>/`.
2. Create a repo in your code hosting site, for example: `https://gitlab.com/<your_namespace>/<your_repo_name>/`
3. Follow the instructions from your code hosting site to create a mirror between `https://github.com/<your_namespace>/<your_repo_name>/` and `https://gitlab.com/<your_namespace>/<your_repo_name>/`.
4. When you are ready to create a Pull Request (PR), follow the steps `(starting at step #6)` from [Forking and Cloning from GitHub to GitHub](#forking-and-cloning-from-github-to-github) and create the PR from `https://github.com/<your_namespace>/<your_repo_name>/`.
## Notes for squashing commits with rebase
- To rebase your commits and squash previous commits, you can use:
```bash
git rebase -i your_topic_branch~(number of commits to combine)
```
- For more details visit [gitready.com](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html)
1. The following would combine the last four commits in the branch `mytopic`.
```bash
git rebase -i mytopic~4
```
2. An editor window opens with the most recent commits indicated: (edit the commands to the left of the commit ID)
```gitattributes
pick 9dff55b2 existing commit comments
squash ebb1a730 existing commit comments
squash 07cc5b50 existing commit comments
reword 9dff55b2 existing commit comments
```
3. Save and close the editor. The next editor window opens: (edit the new commit message). *If you select reword for a commit, an additional editor window will open for you to edit the comment.*
```bash
new commit comments
Signed-off-by: yourname <youremailaddress>
```
4. Save and close the editor for the rebase process to execute. The terminal output should say something like the following:
```bash
Successfully rebased and updated refs/heads/mytopic.
```
5. Once you have a successful rebase, and before you sync your local clone, you have to force push origin to update your repo:
```bash
git push -f origin
```
6. Continue on from step #7 from [Forking and Cloning from GitHub to GitHub](#forking-and-cloning-from-github-to-github)
# Set this only after sourcing pihole-FTL.conf as the gravity database path may
@ -48,7 +48,7 @@ scanList(){
# Iterate through each regexp and check whether it matches the domainQuery
# If it does, print the matching regexp and continue looping
# Input 1 - regexps | Input 2 - domainQuery
"regex")
"regex")
for list in ${lists};do
if[["${domain}"=~ ${list}]];then
printf"%b\n""${list}";
@ -109,15 +109,15 @@ scanDatabaseTable() {
# behavior. The "ESCAPE '\'" clause specifies that an underscore preceded by an '\' should be matched
# as a literal underscore character. We pretreat the $domain variable accordingly to escape underscores.
if[["${table}"=="gravity"]];then
case"${exact}" in
"exact")querystr="SELECT gravity.domain,adlist.address,adlist.enabled FROM gravity LEFT JOIN adlist ON adlist.id = gravity.adlist_id WHERE domain = '${domain}'";;
* )querystr="SELECT gravity.domain,adlist.address,adlist.enabled FROM gravity LEFT JOIN adlist ON adlist.id = gravity.adlist_id WHERE domain LIKE '%${domain//_/\\_}%' ESCAPE '\\'";;
esac
case"${exact}" in
"exact")querystr="SELECT gravity.domain,adlist.address,adlist.enabled FROM gravity LEFT JOIN adlist ON adlist.id = gravity.adlist_id WHERE domain = '${domain}'";;
* )querystr="SELECT gravity.domain,adlist.address,adlist.enabled FROM gravity LEFT JOIN adlist ON adlist.id = gravity.adlist_id WHERE domain LIKE '%${domain//_/\\_}%' ESCAPE '\\'";;
esac
else
case"${exact}" in
"exact")querystr="SELECT domain,enabled FROM domainlist WHERE type = '${type}' AND domain = '${domain}'";;
* )querystr="SELECT domain,enabled FROM domainlist WHERE type = '${type}' AND domain LIKE '%${domain//_/\\_}%' ESCAPE '\\'";;
esac
case"${exact}" in
"exact")querystr="SELECT domain,enabled FROM domainlist WHERE type = '${type}' AND domain = '${domain}'";;
* )querystr="SELECT domain,enabled FROM domainlist WHERE type = '${type}' AND domain LIKE '%${domain//_/\\_}%' ESCAPE '\\'";;
esac
fi
# Send prepared query to gravity database
@ -128,8 +128,8 @@ scanDatabaseTable() {
fi
if[["${table}"=="gravity"]];then
echo"${result}"
return
echo"${result}"
return
fi
# Mark domain as having been white-/blacklist matched (global variable)
@ -233,9 +233,9 @@ for result in "${results[@]}"; do
# Since PHP 7 is available by default, install via default PHP package names
: # do nothing as PHP is current
else
REMI_PKG="remi-release"
REMI_REPO="remi-php72"
rpm -q ${REMI_PKG}&> /dev/null ||rc=$?
if[[$rc -ne 0]];then
# The PHP version available via default repositories is older than version 7
if ! whiptail --defaultno --title "PHP 7 Update (recommended)" --yesno "PHP 7.x is recommended for both security and language features.\\nWould you like to install PHP7 via Remi's RPM repository?\\n\\nSee: https://rpms.remirepo.net for more information""${r}""${c}";then
# User decided to NOT update PHP from REMI, attempt to install the default available PHP version
printf" %b User opt-out of PHP 7 upgrade on CentOS. Deprecated PHP may be in use.\\n""${INFO}"
: # continue with unsupported php version
# If the host OS is Fedora,
if grep -qiE 'fedora|fedberry' /etc/redhat-release;then
# all required packages should be available by default with the latest fedora release
printf" %b Remi's RPM repository has been enabled for PHP7\\n""${TICK}"
# trigger an install/update of PHP to ensure previous version of PHP is updated from REMI
if"${PKG_INSTALL[@]}""php-cli"&> /dev/null;then
printf" %b PHP7 installed/updated via Remi's RPM repository\\n""${TICK}"
REMI_PKG="remi-release"
REMI_REPO="remi-php72"
rpm -q ${REMI_PKG}&> /dev/null ||rc=$?
if[[$rc -ne 0]];then
# The PHP version available via default repositories is older than version 7
if ! whiptail --defaultno --title "PHP 7 Update (recommended)" --yesno "PHP 7.x is recommended for both security and language features.\\nWould you like to install PHP7 via Remi's RPM repository?\\n\\nSee: https://rpms.remirepo.net for more information""${r}""${c}";then
# User decided to NOT update PHP from REMI, attempt to install the default available PHP version
printf" %b User opt-out of PHP 7 upgrade on CentOS. Deprecated PHP may be in use.\\n""${INFO}"
printf" %b Remi's RPM repository has been enabled for PHP7\\n""${TICK}"
# trigger an install/update of PHP to ensure previous version of PHP is updated from REMI
if"${PKG_INSTALL[@]}""php-cli"&> /dev/null;then
printf" %b PHP7 installed/updated via Remi's RPM repository\\n""${TICK}"
else
printf" %b There was a problem updating to PHP7 via Remi's RPM repository\\n""${CROSS}"
exit1
fi
fi
fi# Warn user of unsupported version of Fedora or CentOS
if ! whiptail --defaultno --title "Unsupported RPM based distribution" --yesno "Would you like to continue installation on an unsupported RPM based distribution?\\n\\nPlease ensure the following packages have been installed manually:\\n\\n- lighttpd\\n- lighttpd-fastcgi\\n- PHP version 7+""${r}""${c}";then
printf" %b Aborting installation due to unsupported RPM based distribution\\n""${CROSS}"
exit
else
printf" %b There was a problem updating to PHP7 via Remi's RPM repository\\n""${CROSS}"
exit1
printf" %b Continuing installation with unsupported RPM based distribution\\n""${INFO}"
fi
fi
fi# Warn user of unsupported version of Fedora or CentOS
if ! whiptail --defaultno --title "Unsupported RPM based distribution" --yesno "Would you like to continue installation on an unsupported RPM based distribution?\\n\\nPlease ensure the following packages have been installed manually:\\n\\n- lighttpd\\n- lighttpd-fastcgi\\n- PHP version 7+""${r}""${c}";then
printf" %b Aborting installation due to unsupported RPM based distribution\\n""${CROSS}"
exit
else
printf" %b Continuing installation with unsupported RPM based distribution\\n""${INFO}"
fi
fi
fi
}
# A function for checking if a directory is a git repository
@ -519,7 +519,7 @@ update_repo() {
# In case extra commits have been added after tagging/release (i.e in case of metadata updates/README.MD tweaks)
IMPORTANT: If you have not already done so, you must ensure that this device has a static IP. Either through DHCP reservation, or by manually assigning one. Depending on your operating system, there are many ways to achieve this.
Choose yes to indicate that you have understood this message, and wish to continue" "${r}" "${c}"; then
#Nothing to do, continue
echo
else
printf" %b Installer exited at static IP message.\\n""${INFO}"
exit1
fi
#Nothing to do, continue
echo
else
printf" %b Installer exited at static IP message.\\n""${INFO}"
exit1
fi
}
# A function that lets the user pick an interface to use with Pi-hole
@ -674,7 +674,7 @@ chooseInterface() {
# Feed the available interfaces into this while loop
done<<<"${availableInterfaces}"
# The whiptail command that will be run, stored in a variable
chooseInterfaceCmd=(whiptail --separate-output --radiolist "Choose An Interface (press space to toggle selection)""${r}""${c}""${interfaceCount}")
chooseInterfaceCmd=(whiptail --separate-output --radiolist "Choose An Interface (press space to toggle selection)""${r}""${c}"6)
# Now run the command using the interfaces saved into the array
# Ask if the user wants to use DHCP settings as their static IP
# This is useful for users that are using DHCP reservations; then we can just use the information gathered via our functions
if whiptail --backtitle "Calibrating network interface" --title "Static IP Address" --yesno "Do you want to use your current network settings as a static address?
IP address: ${IPV4_ADDRESS}
Gateway: ${IPv4gw}" "${r}" "${c}"; then
DHCPChoice=$(whiptail --backtitle "Calibrating network interface" --title "Static IP Address" --menu --separate-output "Do you want to use your current network settings as a static address? \\n
IP address: ${IPV4_ADDRESS}\\n
Gateway: ${IPv4gw}\\n" "${r}" "${c}" 3\
"Yes""Set static IP using current values"\
"No""Set static IP using custom values"\
"Skip""I will set a static IP later, or have already done so" 3>&2 2>&1 1>&3)||\
{printf" %bCancel was selected, exiting installer%b\\n""${COL_LIGHT_RED}""${COL_NC}";exit 1;}
case${DHCPChoice} in
"Yes")
# If they choose yes, let the user know that the IP address will not be available via DHCP and may cause a conflict.
whiptail --msgbox --backtitle "IP information" --title "FYI: IP Conflict""It is possible your router could still try to assign this IP to a device, which would cause a conflict. But in most cases the router is smart enough to not do that.
If you are worried, either manually set the address, or modify the DHCP reservation pool so it does not include the IP you want.
It is also possible to use a DHCP reservation, but if you are going to do that, you might as well set a static address." "${r}" "${c}"
# Nothing else to do since the variables are already set above
else
# Otherwise, we need to ask the user to input their desired settings.
# Start by getting the IPv4 address (pre-filling it with info gathered from DHCP)
# Start a loop to let the user enter their information with the chance to go back and edit it if necessary
if ! sqlite3 "${gravityDBfile}" < "${gravityDBschema}";then
echo -e "${CROSS} Unable to create ${gravityDBfile}"
return1
fi
chown pihole:pihole "${gravityDBfile}"
chmod g+w "${piholeDir}""${gravityDBfile}"
}
# Copy data from old to new database file and swap them
@ -213,7 +218,7 @@ database_table_from_file() {
# Move source file to backup directory, create directory if not existing
mkdir -p "${backup_path}"
mv "${source}""${backup_file}" 2> /dev/null ||\
echo -e "${CROSS} Unable to backup ${source} to ${backup_path}"
echo -e "${CROSS} Unable to backup ${source} to ${backup_path}"
# Delete tmpFile
rm "${tmpFile}" > /dev/null 2>&1||\
@ -248,7 +253,7 @@ database_adlist_number() {
return;
fi
output=$({printf".timeout 30000\\nUPDATE adlist SET number = %i, invalid_domains = %i WHERE id = %i;\\n""${num_lines}""${num_invalid}""${1}"| sqlite3 "${gravityDBfile}";} 2>&1)
output=$({printf".timeout 30000\\nUPDATE adlist SET number = %i, invalid_domains = %i WHERE id = %i;\\n""${num_source_lines}""${num_invalid}""${1}"| sqlite3 "${gravityDBfile}";} 2>&1)
status="$?"
if[["${status}" -ne 0]];then
@ -279,7 +284,10 @@ migrate_to_database() {
if[ ! -e "${gravityDBfile}"];then
# Create new database file - note that this will be created in version 1
@ -18,8 +18,8 @@ py.test -vv -n auto -m "build_stage"
py.test -vv -n auto -m "not build_stage"
```
The build_stage tests have to run first to create the docker images, followed by the actual tests which utilize said images. Unless you're changing your dockerfiles you shouldn't have to run the build_stage every time - but it's a good idea to rebuild at least once a day in case the base Docker images or packages change.
The build_stage tests have to run first to create the docker images, followed by the actual tests which utilize said images. Unless you're changing your dockerfiles you shouldn't have to run the build_stage every time - but it's a good idea to rebuild at least once a day in case the base Docker images or packages change.
# How do I debug python?
Highly recommended: Setup PyCharm on a **Docker enabled** machine. Having a python debugger like PyCharm changes your life if you've never used it :)
Highly recommended: Setup PyCharm on a **Docker enabled** machine. Having a python debugger like PyCharm changes your life if you've never used it :)
Adam Warner
2 years ago
committed by