Skip to content

Latest commit

 

History

History
285 lines (183 loc) · 15.4 KB

CONTRIBUTING.md

File metadata and controls

285 lines (183 loc) · 15.4 KB
Raw

Contributing at Layer5

We are beyond excited to see that you want to contribute! We would love to accept your contributions. Layer5 is built by the community and warmly welcomes collaboration. There are many ways in which one could contribute to Layer5 and every contribution is equally appreciated here. Navigate through the following to understand more about contributing here.

Before You Get Started

Code of Conduct

Layer5 follows the Cloud Native Computing Foundation (CNCF) Code of Conduct.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting [email protected]. Violation of the code of conduct is taken seriously, kindly report any violations of the Code of Conduct by filling in the Incident report . The comfort and safety of Layer5 community members is our priority. Please do well to adhere to the Code of Conduct to participate in the Layer5 community.

Newcomers Guide

To help you get started on contributing to Layer5 projects, refer to the Layer5 Newcomers Guide, which aims to make contributions easier for new folks like you! See the resources and tutorials to help you get started.

Style Guide

The Layer5 website is hosted in this repository and is built using Gatsbyjs. Before opening a pull request, please review the design doc to learn more about the structure of the website. Once a pull request has been submitted, a preview deployment will be built and made available to you and other contributors on your PR to review.

Discussion Forum

Join the discussion forum (the Landscape topic is appropriate for all layer5.io questions) to discuss suggested new features, possible bugs, enhancement in user experience, and on any other aspects of the site. The discussion forum is our preferred method of communication, you can, however, also inquire in the #websites channel in the Layer5 Slack workspace.

Contributing to Layer5 Projects

Please follow these steps and note these guidelines to begin contributing:

  1. First step is to set up the local development environment. See this on how to do the same.
  2. Bug fixes are always welcome. Start by reviewing the list of bugs.
  3. A good way to easily start contributing is to pick and work on a good first issue. We try to make these issues as clear as possible and provide basic info on how the code should be changed, and if something is unclear feel free to ask for more information on the issue.
  4. We regularly discuss about new issues to work on in our discussion forumand in the #websites channel. Feel free to join and discuss about any issue or any idea that you may have.

Contributing to Layer5's Blogs

If you'd like to contribute a post to the layer5.io/blog, please open an issue and suggest a topic. If you don't have a topic, then hop into the #blog-kitchen channel, and we'll help you find one.

Common Types of Site Contributions

The following list of instructions pertain to commonplace site updates by contributors.

Things to keep in mind

  1. Use only the theme colors available at themeStyles.js instead of external color codes.
  2. Avoid adding rel="noreferrer" attribute to internal links on the site.

Adding Images and Icons

  1. It is recommended to use @react-icons/all-files instead of react-icons for importing icons. The issue with react-icons is that even though we are importing a single icon from the package/folder it still imports the complete icon folder which is creating unwanted junks of JS in the build.
  2. It is recommended to use Gatsby's <StaticImage> instead of <img> tag to display static images on the site. This performs automatic image optimization, thereby improving site performance.
  3. Avoid creating duplicate copies of same image under different folders. All images must be imported from /assets/images folder.

Adding a Blog Post

  1. In order to contribute a blog post, fork this repository, clone it, create a new branch and navigate to the src/collections/blog directory.
  2. Create a copy of the blog template.
  3. Follow the instructions included in the blog template and name the new file after the title of the blog article.
  4. Entries will be listed in chronological order automatically.

Adding News

  1. In order to add/update news items, fork this repository, clone it, create a new branch and navigate to the src/collections/news directory.
  2. Create a copy of the news template.
  3. Follow the instructions included in the news template and name the new file after the title of the news article.
  4. Entries will be listed in chronological order automatically.

Updating/Creating a Community Member Profile

Layer5 community members are an integral part of what makes Layer5 and it's projects successful. Prominently highlighting our members and their works is something that we think is important. When adding a new or updating an existing community member profile, be sure to use the Community Member Profile issue template which has all the instructions that one may need for this.

Note that the Community Member Profile template is helpful when adding new or updating an existing community member profiles. You can easily understand how the template is used by reviewing other profiles.

Badges for Community Members

Badges are a great way of highlighting the area of contribution by any given community member. A variety of badges exist so that community members and their efforts may be affiliated with a particular project or with a community initiative. An example of how a badge is assigned using markdown can be found here, and it will appear this way on a member profile.

Possible Badges:

  • Community
  • Landscape
  • ImageHub
  • Meshery
  • Meshery Operator
  • SMP
  • Nighthawk
  • Patterns

Updating the Service Mesh Landscape

Another common site update includes updation of the Service Mesh Landscape. The service mesh landscape is powered by Gatsby.js. In order to update the landscape, fork this repository, clone it, create a branch and navigate to the src/collections/landscape folder.

Make sure to open a new issue first. Following are a list of files that you may edit and make the neccessary updates (if appropriate):

Entries should be listed in alphabetical order. Data provided to the smi.js is dynamic and based upon results from conformance tests run using Meshery.

To update the Service Mesh Timeline, add the new service mesh in the non-functional.js file. Add announce-date key for the service mesh, then add a timeline-order key having a value 1+maximum value of timeline-order till now, to list the service mesh in the timeline correctly.

How to Contribute

Prequisites

Make sure you have the following prerequisites installed on your operating system before you start contributing:

Note: If you're on a Windows environment then it is highly recommended that you install Windows Subsystem for Linux (WSL) both for performance and ease of use. Refer to the documentation for the installation of Gatsby.js on WSL.

Set up your Local Development Environment

Follow the following instructions to start contributing.

1. Fork this repository.

2. Clone your forked copy of the project.

git clone https://github.com/<your-github-username>/layer5.git

3. Navigate to the project directory.

cd layer5

4. Add a reference(remote) to the original repository.

git remote add upstream https://github.com/layer5io/layer5.git

5. Check the remotes for this repository.

git remote -v

6. Always take a pull from the upstream repository to your master branch to keep it at par with the main project (updated repository).

git pull upstream master

7. Create a new branch.

git checkout -b <your_branch_name>

8. Install the dependencies for running the site.

make setup-libs

9. Make the desired changes.

10. Run the site locally to preview changes.

make site

This will run a local web server with "live reload" conveniently enabled. ( NOTE: while using make command on Windows, there sometimes arises an error in identifying the command even after it is installed (unrecognized command), this is because the PATH for the binary might not be set correctly ).

11. Track your changes.

git add .

12. Commit your changes. To contribute to this project, you must agree to the Developer Certificate of Origin (DCO) for each commit you make.

git commit --signoff -m "<commit subject>"

or you could go with the shorter format for the same, as shown below.

git commit -s -m "<commit subject>"

13. While you are working on your branch, other developers may update the master branch with their branch. This action means your branch is now out of date of the master branch and missing content. So in order to fetch the new changes, follow along:

git checkout master
git fetch origin master
git merge upstream/master
git push origin

Now you need to merge the master branch into your branch. This can be done in the following way:

git checkout <your_branch_name>
git merge master

14. Push the committed changes in your feature branch to your remote repo.

git push -u origin <your_branch_name>

15. Once you’ve committed and pushed all of your changes to GitHub, go to the page for your fork on GitHub, select your development branch, and click the pull request button. Please ensure that you compare your feature branch to the desired branch of the repo you are supposed to make a PR to. If you need to make any adjustments to your pull request, just push the updates to GitHub. Your pull request will automatically track the changes in your development branch and update it.

Signing-off on Commits

To contribute to this project, you must agree to the Developer Certificate of Origin (DCO) for each commit you make. The DCO is a simple statement that you, as a contributor, have the legal right to make the contribution.

See the DCO file for the full text of what you must agree to and how it works here. To signify that you agree to the DCO for contributions, you simply add a line to each of your git commit messages:

Signed-off-by: Jane Smith <[email protected]>

Note: you don't have to manually include this line on your commits, git does that for you as shown below:

$ git commit -s -m “my commit message w/signoff”

In most cases, git automatically adds the signoff to your commit with the use of -s or --signoff flag to git commit. You must use your real name and a reachable email address (sorry, no pseudonyms or anonymous contributions).

To ensure all your commits are signed, you may choose to add this alias to your global .gitconfig:

~/.gitconfig

[alias]
  amend = commit -s --amend
  cm = commit -s -m
  commit = commit -s

Or you may configure your IDE, for example, Visual Studio Code to automatically sign-off commits for you: