# Cnnect Home - *amrodconnect.co.za*
The heart of the whole Cnnect system!
---

## Documentation Overview
- Moving forward, each directory in the repo will be given a `README.md` documentation file briefly describing the *purpose* and *usage* of the directory.
    - The **directory purpose** is the reason the directory exists.
    - The **directory usage** is the manner in which any changes to the directory should be made.
        - any established rules for the directory (i.e. "Only for assets related to x feature for client y", or "Only for system use")
        - any no-no's for the directory (i.e. "Should never be accessible to the webserver", or "Should never be altered manually")
- Beyond this, we won't put in place hard rules about the contents of the README files as novel circumstances may necessitate novel documentation. If we have a `purpose` and a `usage` present then the rest of the README may contain whatever information can help a new developer stumbling upon the directory.
- ***Note:*** The `README.md` files are purely for the sake of this repository and it's developers and are programmatically excluded from the ftp-deploy workflow. They do not get transferred to the production server, and as such can house sensitive system information if need be.

## Repository Exclusions Overview
The repository's exclusions are the files and folders which either should not be shared between developers, or which should not be transferred from the repo to the production server.

### Different Exclusion Types:
There are 2 types of file exclusions in our deployment pipeline:

### .gitignore File Exclusions:
These are files, directories, paths or glob patterns to be excluded from git's file tracking altogether.

*Maintaining this file and it's exclusions is the responsibility of all Cnnect developers*

If a file or folder is being ignored by git (i.e. it is listed in the `.gitignore` file) then your local version will never be changed on `git pull`, it will not be added to your staged files with `git add` unless the force flag (`-f` or `--force`) is used.

To clear up any confusion on this behaviour, see the [following snippet](https://git-scm.com/docs/gitignore#_notes) from the "Notes" section on the git-scm docs page for the gitignore file:

>The purpose of gitignore files is to ensure that certain files not tracked by Git remain untracked.
>
>To stop tracking a file that is currently tracked, use git rm --cached to remove the file from the index. The filename can then be added to the `.gitignore` file to stop the file from being reintroduced in later commits.
>
>Git does not follow symbolic links when accessing a `.gitignore` file in the working tree. This keeps behavior consistent when the file is accessed from the index or a tree versus from the filesystem.

For a working example let's take what happened with our project's `conn.php` file:
- Originally, the `conn.php` file was excluded by being referenced in the root directory's `.gitignore` file.
- A version of the file was manually transferred to the server to allow a database connection.
    - At this point, all is well and git should not interfere with the file.
    - This does mean, however, all devs have to have a local version of the same file which is not tracked if they want to serve the project in their local environment.
- Later, the `conn.php` file was forcefully added and pushed to the repo. overwriting the untracked version on the server and adding it to git's index (git starts tracking the file)
    - From this point, if you do nothing, git will no longer allow you to treat the file as though it is untracked/ignored.
    - If your local version is different, it will not let you pull without a `stash` or a `commit`.
    - If your local version is different *and* committed, it will force you to merge them.
    - (Naturally this is a significant workflow interruption)
    - The fix here is to:
        - 1st: Make a backup of the version of the file which is supposed to be live (and untracked) on the production server.
        - 2nd: Ensure the file (`conn.php`) is still listed in the `.gitignore` file.
        - 3rd: (Assuming you want to restore the state of exclusion) use `git rm --cached {filename}` (i.e. `git rm --cached conn.php`) to remove it from git's index and start ignoring it again.
    - Once these steps are followed, your local version of the file (in your "working tree") should remain and the repository should once again be ignoring the file, allowing you to have your own local version without affecting the production server's state.
    - The file hosted on the production server will be deleted at this point by the ftp-deploy action. Be sure to manually transfer the live version back to the server once this happens, after this you should never need to touch it again.

### ftp-deploy File Exclusions:
These are files, directories, paths or glob patterns to be excluded from the FTP-Deploy workflow on a push to the main branch.

*Maintaining this file and it's exclusions is the responsibility of Cnnect's **Dev-Ops engineer***

As long as our `.gitignore` is functioning correctly and is up-to-date, there is not much that has to be handled at this stage of the deployment pipeline, but it is still important that it remains functional.

The following are the default exclusions for this file:
>          **/.git*
>          **/.git*/**
>          **/node_modules/**

Despite having no /node_modules/ folder we are keeping the exclusion for the sake of compatibility with the library's future updates.

The only custom exclusion currently added is:
>          **/README.md

And this glob pattern should match all `README.md` documents across the project repository, preventing them from being transferred to the production server.