Merge branch 'feat/contribution-guide' into 'main'

doc(contrib): add basic contribution guides

See merge request integration/ringcentral-integration-docs!21

Author: u9520107

.vscode/settings.json

@@ -3,6 +3,7 @@
         "Archiver",
         "gdrive",
         "HubSpot",
+        "Mkdocs",
         "RingCentral",
         "Smarsh"
     ]

CONTRIBUTION.md

@@ -0,0 +1,97 @@
+# Contribution Guidelines
+
+## Creating new branch to work on the repository
+
+1. Always create a new branch from the current main branch when you start to work on a new feature.
+2. In the terminal, this can be in the VSCode terminal. Make sure you are in the main branch.
+
+    ```bash
+    git checkout main
+    ```
+
+3. Now we want to make sure that the main branch is up to date.
+
+    ```bash
+    git pull
+    ```
+
+4. Now we want to create a new branch from the main branch. You can name the branch whatever you want, but it is recommended to use a descriptive name. For example, if you are working on new features, feat/new-feature-name is a good name. If you are fixing some issues, fix/issue-name is a good name.
+
+    ```bash
+    git checkout -b "branch-name"
+    ```
+
+5. Now you are set to start working on the new features.
+
+## Committing changes
+
+1. When you are done with the changes, or if you want to save the progress, you can commit the changes.
+2. In the terminal, first you want to add the changes to the staging area. The `.` means all files in the current directory.
+
+    ```bash
+    git add .
+    ```
+
+3. Now you can commit the changes. It's recommended to use a descriptive commit message. For example, we use this format in our integration-apps repo: `type(scope): [ticket-id] message`.
+
+    ```bash
+    git commit -m "commit message"
+    ```
+
+    - For this project, the type is probably just 'feat' or 'fix'.
+    - The scope is to show what part of the project you worked in, this can be as broad as HubSpot, or SalesForce, or as specific as SF-AAL.
+    - If there are jira tickets, you can put it in the ticket-id portion. Our gitlab has an integration to link with Jira.
+    - Be descriptive in the message, but keep it short and concise.
+    - There are not strict rules on the format currently, but it's recommended to follow the format above.
+
+## Pushing changes to the remote repository
+
+1. Once you are done with the changes and all of the changes are committed, you can push the changes to the remote repository, or back to gitlab server.
+2. Use the following command to push the changes to the remote repository.
+
+    ```bash
+    git push origin "branch-name" -u
+    ```
+
+    - origin is the name of the remote repository, this should be pointing to the main gitlab repository.
+    - if someone else has already pushed to the remote repository with the same branch name, you will run into contacts. You can rename your branch by checking it out as a different branch and then push again with the new name.
+
+        ```bash
+        git checkout -b "new-branch-name"
+        ```
+
+    - the `-u` flag is to set the upstream branch. This allows you to commit new changes to the same branch if the review process asked for changes. Then you can just use `git push` to push the changes.
+
+## Creating a merge request
+
+1. Once you have pushed the changes to the remote repository, you can create a merge request to the main branch.
+2. In the gitlab website, go to the repository page and click on the "Merge Requests" tab.
+3. Click on "New merge request".
+4. Select the source branch and the target branch. The source branch is the new branch you just pushed. The target branch is the main branch.
+5. Click on "Create merge request".
+6. Now you can review the changes and merge the changes to the main branch. Currently, there are no strict reviewing rules, but you should always ask for another person to review the changes.
+
+## After the merge request is merged
+
+1. The remote branch should be deleted automatically if you did not change the merge request settings.
+2. You can now go back to your local main branch and pull the latest changes with the following command:
+
+    ```bash
+    git checkout main
+    git pull
+    ```
+
+3. You should now delete the merged local branch with the following command:
+
+    ```bash
+    git branch -D "branch-name"
+    ```
+
+    - The `-D` flag is to force delete the branch. Sometime git does not recognize the local branch as merged, so we have to use the force flag.
+
+4. It is important to never start working on a new feature from an old branch. Always create a new branch from the main branch.
+
+## Viewing the merged results
+
+1. Merging the request will trigger an internal build. You can review the result usually in a few minutes.
+2. If the build is successful, the changes will be deployed to the test environment. You can review the changes in the [gitlab pages site](http://integration.pages.git.ringcentral.com/ringcentral-integration-docs/).

GITLAB-SETUP.md

@@ -0,0 +1,90 @@
+# RingCentral Gitlab Setup
+
+Please note that these are just standard instructions meant for people who are not familiar with Gitlab and SSH. These are not specific rules that you have to follow if you know what you are doing. This also assume that you are using a Mac.
+
+## Gitlab access
+
+1. Go to git.ringcentral.com and login.
+2. If you do not have access to our gitlab, please go file a ticket in FreshService to request for access.
+3. Once you have access, please reach out to Jack Huang via Glip to get added to the repository.
+
+## Generate SSH key
+
+1. Open the terminal.
+2. Run the following command to generate a new SSH key:
+
+    ```bash
+    ssh-keygen -t ed25519 -C "[email protected]"
+    ```
+
+3. This will prompt you to enter a passphrase. This is optional. Entering the passphrase will make it more secure, but you will have to enter the passphrase every time you push to Gitlab. This is usually not needed for this use.
+4. The SSH key will be generated in the `~/.ssh` directory.
+5. Run the following command to make sure the SSH agent is running:
+
+    ```bash
+    eval "$(ssh-agent -s)"
+    ```
+
+6. Add the SSH key to the SSH agent:
+
+    ```bash
+    ssh-add ~/.ssh/id_ed25519
+    ```
+
+## Add SSH key to Gitlab
+
+1. In our gitlab site, click on your profile picture and go to "Preferences".
+2. Click on "SSH Keys" in the left sidebar.
+3. Under SSH Keys, click on "Add new key".
+4. Paste the SSH key you generated in the previous step into the "Key" field.
+5. Click on "Add Key".
+6. Back in the terminal, run the following command to copy the SSH key to the clipboard:
+
+    ```bash
+    pbcopy < ~/.ssh/id_ed25519.pub
+    ```
+
+7. Paste the SSH key into the "Key" field in the Gitlab website.
+8. Optionally, you can remove the expiration date if do not want to have to update the key later.
+9. Click on "Add Key".
+
+## Cloning the repository
+
+1. Back in the terminal, first go back to your home directory:
+
+    ```bash
+    cd ~
+    ```
+
+2. Then create a workplace directory if you do not have on yet. You can name it whatever you want, but workspace is a good name:
+
+    ```bash
+    mkdir -p ~/workplace
+    ```
+
+3. Then go to the workplace directory:
+
+    ```bash
+    cd ~/workplace
+    ```
+
+4. Then clone the repository:
+
+    ```bash
+    git clone [email protected]:ringcentral/ringcentral-docs.git
+    ```
+
+5. If this is the first time you are cloning repositories from our gitlab, the system will prompt you to confirm on adding the host to the known hosts file. Type "yes" and press enter.
+
+6. Now the repository is cloned.
+
+## Global git config
+
+It is also recommended to set the global git config up first if you have not done this before. Mainly, we need to set the user name and email so that you can create commits. In the terminal, run the following command:
+
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "[email protected]"
+```
+
+That sets the user name and email for all repositories on your machine.

LOCAL-SETUP.md

@@ -0,0 +1,66 @@
+# Local Environment Setup
+
+## IDE Setup
+
+There's a number of editors or IDEs that you can use to edit this project. But generally we recommend using VSCode, or Cursor if you have access to it.
+
+Here we assume you are using VSCode, people with Cursor access should be able to skip these steps.
+
+1. To install VSCode, go to [VSCode](https://code.visualstudio.com/) and download the installer for MacOS. Then just follow the standard MacOS app installation process.
+2. Once VSCode is installed, open it.
+3. Now, we want to install the shell command to make it easier to run VSCode from the terminal.
+4. In VSCode, use Cmd+Shift+P to open the command palette.
+5. Type "shell command" and select "Shell Command: Install 'code' command in PATH".
+6. This will install the `code` command in your terminal.
+7. Now you can use the `code` command to open VSCode from the terminal.
+8. To test this, go back to the terminal. Close the terminal and open a new one to ensure that it has the latest PATH environment variable.
+9. Assuming that you have already cloned the repository into the recommended directory, you can now open the project in VSCode by running the following command:
+
+    ```bash
+    code ~/workplace/ringcentral-integration-docs
+    ```
+
+10. That should open the project in VSCode.
+
+## Homebrew Setup
+
+It is recommended to use Homebrew to install the dependencies for this project.
+
+1. To install Homebrew, go to [Homebrew](https://brew.sh/) and follow the instructions.
+2. Once Homebrew is installed, re-open the terminal to ensure that it has the latest context.
+
+## Python 3 Setup
+
+Mkdocs is implemented in Python 3, so we need to make sure that Python 3 is installed. We can now use Homebrew to install Python 3.
+
+1. Run the following command to install Python 3:
+
+    ```bash
+    brew install python3
+    ```
+
+2. Once Python 3 is installed, run the following command to check if it is installed correctly:
+
+    ```bash
+    python3 --version
+    ```
+
+## Dependencies Setup
+
+1. Now go back to VSCode with our project open.
+2. If the terminal is already open, close it and open a new one. You can use Ctrl+` to open the terminal.
+3. Run the following command to install the dependencies:
+
+    ```bash
+    pip3 install -r requirements.txt
+    ```
+
+4. Once the dependencies are installed, you can close the terminal and reopen it to ensure that the dependencies are loaded.
+
+5. Now you should be able to start the development server by running the following command:
+
+    ```bash
+    mkdocs serve
+    ```
+
+6. This will start the development server and you can now open the site in your browser by going to [http://127.0.0.1:8000](http://127.0.0.1:8000).

README.md

@@ -6,11 +6,7 @@ This repository contains the documentation for the RingCentral Integration Apps.
 
 The site is build using [Mkdocs](https://www.mkdocs.org/) and [Mkdocs Material](https://squidfunk.github.io/mkdocs-material/).
 
-Make sure you have python3 installed. On Mac, you can install it using Homebrew.
-
-```bash
-brew install python3
-```
+Make sure you have python3 installed.
 
 Then install the dependencies. Assuming that you have not override the default python3 path, you can install the dependencies by running the following command.
 
@@ -24,6 +20,15 @@ Then you can run the development server by running the following command.
 mkdocs serve
 ```
 
+See [LOCAL-SETUP.md](LOCAL-SETUP.md) for detailed instructions if needed.
+
+## Contribution
+
+1. Forking is not required. You can just clone the repository and start contributing.
+2. Please always create a new branch from the main branch and create merge-requests to the main branch.
+
+See [CONTRIBUTION.md](CONTRIBUTION.md) for more details.
+
 ## Plans
 
 1. Start with a basic site structure
@@ -34,10 +39,6 @@ mkdocs serve
 
 ## TODO
 
-- [ ] Create github repo
-- [ ] Prepare github publication scripts
 - [ ] Submit SEO results to RC main support site
 - [ ] Create a process to build internal contents
 - [ ] Create a process to build public contents
-  - [ ] Figure out where to host internal docs
-  - [ ] Create a build script to push public contents to github so everything is maintained in gitlab