Istio is the most popular service mesh in the industry today. It is backed by a comprehensive documentation hosted at https://istio.io/latest/docs/
Like any open source project, Istio's documentation relies heavily on the contributions from the community. If you are passionate about documentation and would like to make a contribution, the first step is to set up the documentation site locally. In this article, we will learn the basic steps to achieve this.
Prerequisites
Local Setup
Fork the repository
Create a fork of the istio/istio.io repository
Clone the fork
💡
Use the url of your forked repo
git clone https://github.com/adityasamant25/istio.io
Create a branch
💡
'issue-10' has been used as an example for the branch name
// Navigate to the project directory
cd istio.io
git checkout -b issue-10
Deploy the website locally
Istio provides a Docker image with all the tools needed, including Hugo which is the site generator. To build and publish the website locally within the docker container, execute the command below:
make serve
💡
In case you receive an error stating "Failed to read Git log: fatal: detected dubious ownership in repository at '/work'", execute the below command locally and then run the make serve command again.
git config --global --add safe.directory /work
Once the website builds successfully, you should see the following message:
Built in 18037 ms
Environment: "development"
Serving pages from disk
Web Server is available at http://localhost:1313/latest/ (bind address 0.0.0.0)
Access the URL http://localhost:1313/latest/ from within a browser. The Istio documentation is now available to you locally.
Contribute changes
The documentation for the English language is available at the following path:
/content/en/docs
Navigate to the .md file you need to edit. Make the appropriate changes and save the file. Saving the changes automatically triggers a redeployment of the site. The browser refreshes automatically and this enables you to immediately validate your changes locally.
Once you are satisfied with your changes, perform the following steps:
Commit the changes to your local branch
git add <file paths>
git commit -m "Fixed issue 10"
Push the changes to a branch on your fork
git push origin issue-10
Raise a pull request from your branch to the istio.io master branch
After you raise a pull request, wait for a maintainer to review the changes. In case of any review comments, incorporate the changes and push a new commit.
Conclusion
Hope this article helps in getting you started on your journey to contribute to Istio documentation. In case of any issues, please post a reply and I will try to assist.
