Re: svn commit: r1872744 - /bloodhound/branches/bh_core_experimental/README.md

[Gary Martin <ga...@physics.org>]

As mentioned, I was messing around with the instructions last night and so this is the patch that went in on that basis.

Included there is a bit of updated advice for ways to get the code - the methods may not really be best practice but I was aiming for conciseness and consistency between the svn and github routes.

You can look here for the current state on the branch: http://svn.apache.org/viewvc/bloodhound/branches/bh_core_experimental/README.md?view=markup

Some people may prefer the equivalent on github for a prettier view: https://github.com/apache/bloodhound/blob/bh_core_experimental/README.md

If anyone can spot better instructions for selenium installation, then that could be useful as it would save my temptation to write a python script for downloading and installing in a cross platform fashion that I may find difficult to test!

Cheers!

On Tue, 14 Jan 2020, at 2:06 AM, gjm@apache.org wrote:
> Author: gjm
> Date: Tue Jan 14 02:06:28 2020
> New Revision: 1872744
> 
> URL: http://svn.apache.org/viewvc?rev=1872744&view=rev
> Log:
> Updates to setup advice
> 
> Modified:
>     bloodhound/branches/bh_core_experimental/README.md
> 
> Modified: bloodhound/branches/bh_core_experimental/README.md
> URL: 
> http://svn.apache.org/viewvc/bloodhound/branches/bh_core_experimental/README.md?rev=1872744&r1=1872743&r2=1872744&view=diff
> ==============================================================================
> --- bloodhound/branches/bh_core_experimental/README.md (original)
> +++ bloodhound/branches/bh_core_experimental/README.md Tue Jan 14 
> 02:06:28 2020
> @@ -1,61 +1,67 @@
>  # New Bloodhound
>  
> -## Requirements
> +## Getting the Bloodhound Code:
>  
> -### Python
> +There is a reasonable chance that you are reading these instructions from a
> +copy of the source code that you have already placed on the computer that you
> +wish to install on. If this is the case you can skip on to the next section.
>  
> -Bloodhound core is currently written in Python3. It should be possible to
> -install and run the core successfully with Python 3.6 or newer. You may
> -find that versions from Python 3.4 work but this is not currently tested
> -and it is possible that Python features from newer versions may sneak in.
> +While in early development, the alternatives for getting the code include
> +checking out from [Subversion] with the following command:
>  
> -If you do not already have an appropriate version of Python installed, 
> you
> -may wish to follow instructions for your platform here:
> +```
> +svn checkout 
> https://svn.apache.org/repos/asf/bloodhound/branches/bh_core_experimental/ bloodhound
> +```
>  
> -  https://docs.python-guide.org/starting/installation/
> +or cloning with [Git] from the [Apache Bloodhound Github mirror] - the command
> +below should also check out the appropriate branch:
>  
> -### Pipenv
> +```
> +git clone --branch bh_core_experimental 
> https://github.com/apache/bloodhound.git
> +```
>  
> -Pipenv is used for looking after Python package dependencies and virtual
> -environment management.
> +With the commands as specified, both will place the code in the `bloodhound`
> +directory.
>  
> -If you already have the `pip` program installed already, installation of
> -pipenv can be as simple as
> +[Subversion]: https://subversion.apache.org/
> +[Git]: https://git-scm.com/
> +[Apache Bloodhound mirror]: https://github.com/apache/bloodhound
> +[Github]: https://github.com/
>  
> -```
> -pip install --user pipenv
> -```
> +## Installing Python and Pipenv
>  
> -For more information on installing and usage of pipenv, see
> -https://docs.pipenv.org/.
> +Bloodhound core is currently written in [Python 3] and uses [Pipenv] for
> +looking after the python based dependencies.
>  
> -Once pipenv is installed, the final bit of setup ahead of installing the
> -rest of the project dependencies is to ensure that you have picked out the
> -appropriate version of Python for your environment. For the same directory
> -as the `Pipfile` for the project, you should run:
> +It should be possible to install and run the core successfully with Python 3.6
> +or newer. You may find that versions from Python 3.4 work but this is not
> +currently tested and it is possible that Python features from newer versions
> +may sneak in.
>  
> -```
> -pipenv --python 3
> -```
> +The guide at <https://docs.python-guide.org/> gives good instructions for
> +installing Python on [Linux][Python on Linux], [MacOS][Python on MacOS] and
> +[Windows][Python on Windows].
>  
> -If you have multiple versions of Python 3 installed, you may need to be
> -more specific about the version.
> +Further information about pipenv is available at <https://docs.pipenv.org/>.
>  
> -### Pipfile Specified Requirements
> +[Python 3]: https://docs.python.org/3/
> +[Pipenv]: https://pipenv.readthedocs.io/en/latest/
> +[Python on Linux]: 
> https://docs.python-guide.org/starting/install3/linux/#install3-linux
> +[Python on MacOS]: 
> https://docs.python-guide.org/starting/install3/osx/#install3-osx
> +[Python on Windows]: 
> https://docs.python-guide.org/starting/install3/win/#install3-windows
>  
> -With pipenv installed and the Python version selected, the rest of the
> -Python based requrements can be installed with the following command from
> -the same director as the `Pipfile` for the project:
> +## Preparing the Python environment
>  
> -```
> -pipenv install
> -```
> +It should now be possible to use pipenv to install the rest of the project
> +dependencies and bloodhound itself. Note that the exactly required command may
> +depend on details like whether you have multiple versions of python available
> +but for most cases, the following should work. If in doubt, just be more
> +specific about the python version that you intend to use.
>  
> -Additionally, to run tests described later, you should install the
> -development dependencies:
> +For the same directory as the `Pipfile` for the project run:
>  
>  ```
> -pipenv install --dev
> +pipenv --python 3 install
>  ```
>  
>  ## Setup
> @@ -104,27 +110,28 @@ These paths are subject to change.
>  Unit tests are currently being written with the standard unittest framework.
>  This may be replaced with pytest.
>  
> -The tests may be run with the following command:
> +Running the tests require a little extra setup:
>  
>  ```
> -pipenv run python manage.py test
> +pipenv install --dev
>  ```
>  
> -Fixtures for tests when required can be generated with:
> +after which the tests may be run with the following command:
>  
>  ```
> -pipenv run python manage.py dumpdata trackers --format=yaml --indent=2 
> > trackers/fixtures/[fixture-name].yaml
> +pipenv run python manage.py test
>  ```
>  
>  ## Integration Tests
>  
> -Selenium tests currently require that Firefox is installed and 
> `geckodriver` is
> -also on the path. One way to do this is (example for 64bit linux 
> distributions):
> -
> +The [Selenium] tests currently require that Firefox is installed and
> +[geckodriver] is also on the path. If you 
>  ```
> -BIN_LOCATION="$HOME/.local/bin"
>  PLATFORM_EXT="linux64.tar.gz"
> -TMP_DIR=/tmp
> +BIN_LOCATION="$HOME/.local/bin"
> +TMP_DIR=/tmp/geckodriver_download
> +mkdir -p "$BIN_LOCATION" "$TMP_DIR"
> +
>  LATEST=$(wget -O - 
> https://github.com/mozilla/geckodriver/releases/latest 2>&1 | awk 
> 'match($0, /geckodriver-(v.*)-'"$PLATFORM_EXT"'/, a) {print a[1]; 
> exit}')
>  wget -N -P "$TMP_DIR" 
> "https://github.com/mozilla/geckodriver/releases/download/$LATEST/geckodriver-$LATEST-$PLATFORM_EXT"
>  tar -x geckodriver -zf "$TMP_DIR/geckodriver-$LATEST-$PLATFORM_EXT" -O 
> > "$BIN_LOCATION"/geckodriver
> @@ -140,3 +147,14 @@ pipenv run python functional_tests.py
>  
>  There are currently not many tests - those that are there are in place 
> to test
>  the setup above and assume that there will be useful tests in due 
> course.
> +
> +[Selenium]: https://selenium.dev/
> +[geckodriver]: 
> https://firefox-source-docs.mozilla.org/testing/geckodriver/
> +
> +## Development notes:
> +
> +Fixtures for tests when required can be generated with:
> +
> +```
> +pipenv run python manage.py dumpdata trackers --format=yaml --indent=2 
> > trackers/fixtures/[fixture-name].yaml
> +```
> 
> 
>

-- 
Cheers,
    Gary