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
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-10Deploy 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 serveIn 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 /workOnce 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/docsNavigate 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-10Raise 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.
Comments