word-smithing pass
Change-Id: Ie72d7879e50475fa88eb77659f8093b63a83d357
(cherry picked from commit 028c3cd1d5c0d49eea2f1e765bd7bdbf0a596a79)
diff --git a/docs/tutorials/local_synchronizer_dev_loop.md b/docs/tutorials/local_synchronizer_dev_loop.md
index 293c6fd..31ae872 100644
--- a/docs/tutorials/local_synchronizer_dev_loop.md
+++ b/docs/tutorials/local_synchronizer_dev_loop.md
@@ -1,45 +1,32 @@
-# Development of synchronizers in the local scenario
+# Developing Synchronizers Using the Local Scenario
-In some cases is possible to completely write a synchronizer in using the local
-scenario, if that is possible for the integration with your VNF, this workflow
-will speed up your development cycle by a lot.
+It is sometimes possible to develop a synchronizer entirely
+within the local scenario. This results in a simple and efficient
+development loop. A synchronizer can be developed locally
+as long as:
-Note that this document assume that you are already confident with writing XOS
-services, the build system and the CORD terminology. It also assumes that you
-have an XOS service in a good status.
+* The VNF independently executes somewhere that you can connect to
+from your local machine.
+* The VNF does not require OpenStack be deployed as part of the POD.
-It’s possible to work on a synchronizer locally as long as:
+> Note: The following assumes: (1) you have a local scenario up and
+> running, with the service you are working on on-boarded; and (2) you
+> obtained the source code as per [Getting the Code](/getting_the_code.md).
-* The VNF can be executed somewhere that we can connect to from our machine
-* The VNF does not require OpenStack to be deployed
+## Edit docker-compose File
-> NOTE: Some of this steps can be used also in a more complex scenario, for
-> example “virtual” also know as Cord-in-a-box
+A `docker-compose.yml` file was generated during the build process,
+and it is located in the `cord_profile` directory that was also generated
+(typically on the side of your root cord directory). For example, you
+might find your compose file in `~/cord_profile/docker-compose.yml`.
-From now on this guide will assume that:
+Open it with you favorite editor and locate your service synchronizer.
+You will need to add a `command: sleep 86440` to prevent the
+synchronizer from starting automatically and a volume mount to share
+the synchronizer code with your filesystem.
-* you have a local scenario up and running, with the service you are working on
- onboarded
-
-* You obtained the source code as per [Getting the Code](/getting_the_code.md)
-
-## Tweak your docker-compose file
-
-There are few changes you need to make to the docker-compose.yml file in order
-to really shorten your development loop.
-
-A `docker-compose.yml` file for XOS has been generated during the build and it
-is located in the cord_profile directory. Note that the cord_profile directory
-is generated on the side of your cord root folder, so you should find your
-compose file in `~/cord_profile/docker-compose.yml`
-
-Open it with you favorite editor and locate your service synchronizer. You’ll
-need to add a `command: sleep 86440` to prevent the synchronizer from starting
-automatically and a volume mount to share the synchronizer code with your
-filesystem.
-
-Here is an example of a modified synchronizer block (only the meaningful fields
-have been reported here):
+The following is an example of a modified synchronizer block; only the
+meaningful fields have been reported:
```yaml
<service>-synchronizer:
@@ -53,14 +40,15 @@
- /home/user/cord/orchestration/xos_services/<service>/xos/synchronizer:/opt/xos/synchronizers/<service>
```
-> NOTE: The important bits here are the sleep command and the last volume
-> mount, leave everything else untouched.
+The important bits are the sleep command and the last volume
+mount. Leave everything else untouched.
-## Development loop
+## Development Loop
-As first we’ll need to restart the project to apply the changes we made in the
-docker-compose file. To do this we can use docker-compose native commands, so
-from the `cord_profile` directory execute:
+As a first step you will need to restart the local scenario to apply the
+changes made in the `docker-compose` file. To do this, use
+`docker-compose` native commands. From the `cord_profile`
+directory execute:
```shell
docker-compose -p <profile-name> up -d
@@ -69,50 +57,48 @@
> NOTE: The `<profile-name>` is the first part of any XOS container name, so
> you can easily discover it with `docker ps`.
-At this point everything is up and running, except our synchronizer, since that
-is up but sleeping. We need to connect to the docker container with:
+At this point everything is up and running, except your synchronizer, which
+is sleeping. Connect to the docker container with:
```shell
docker exec -it <synchronizer-container> bash
```
-We’ll find ourself in the synchronizer folder, and to start the synchronizer
-it’s enough to call `bash run.sh`.
+You will find yourself in the synchronizer folder. To start the synchronizer,
+simply call `bash run.sh`.
-> NOTE: The filename can be different here and you can also directly start the
-> python process
+> NOTE: The filename can be different, and you can also directly start the
+> python process.
-From now on, you can just make changes at the code on your local filesystem and
-restart the process inside the container to see the changes.
+From now on, you can just make changes to the code on your local
+filesystem and restart the process inside the container to see the changes.
-## Appendix
+## Additional Notes
-Note that if you have the VNF running on you machine and you need to connect to
-it, you can find the host ip from inside a docker container using:
+If the VNF is running on your machine and you need to connect to
+it, you can find the host IP address from inside a docker container using:
```shell
/sbin/ip route|awk '/default/ { print $3 }'
```
-So you easily can have an onos running on you machine, and have your
-synchronizer talk to it to quickly verify the changes.
+You can also easily have ONOS running on your local machine, and have
+your synchronizer talk to it to verify expected behavior.
-The same exact workflow will apply to changes in model policies, while if you
-make changes to the `xproto` model definition or to the `_decl` model
-extension, you will have to rebuild the core container.
+The same exact workflow will apply to changes made to model policies,
+but if you make changes to the `xproto` model definition or to the `_decl`
+model extension, you will have to rebuild the core container.
-If the model changes are in the logic only (eg: you are overriding the default
-save method) you can rebuild and restart the container, and here is a command
-that you use:
+If the model changes are in the logic only (e.g., you are overriding the default
+save method), you can rebuild and restart the container as follows:
```shell
rm milestones/local-start-xos && rm milestones/local-core-image && make build
```
-While if you made model changes (eg: added/remove a field) you need to teardown
+If you made model changes (e.g., added or remove a field), you need to teardown
the database container and recreate it, so the command will be:
```shell
make xos-teardown && make build
```
-