1 line
15 KiB
JavaScript
1 line
15 KiB
JavaScript
"use strict";(self.webpackChunklaradock_documentation=self.webpackChunklaradock_documentation||[]).push([[459],{6564:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>a,contentTitle:()=>o,default:()=>h,frontMatter:()=>r,metadata:()=>l,toc:()=>d});var i=s(4848),t=s(8453);const r={sidebar_position:100,title:"Contributions"},o=void 0,l={id:"contributing",title:"Contributions",description:"Open in Gitpod",source:"@site/docs/contributing.md",sourceDirName:".",slug:"/contributing",permalink:"/docs/contributing",draft:!1,unlisted:!1,editUrl:"https://github.com/laradock/laradock/tree/master/DOCUMENTATION/docs/contributing.md",tags:[],version:"current",sidebarPosition:100,frontMatter:{sidebar_position:100,title:"Contributions"},sidebar:"tutorialSidebar",previous:{title:"Related Projects",permalink:"/docs/related-projects"}},a={},d=[{value:"Have a Question",id:"have-a-question",level:2},{value:"Found an Issue",id:"found-an-issue",level:2},{value:"Want a Feature",id:"want-a-feature",level:2},{value:"Update the Documentation (Site)",id:"update-the-documentation-site",level:2},{value:"Host the Documentation Locally",id:"host-the-documentation-locally",level:3},{value:"Support new Software (Add new Container)",id:"support-new-software-add-new-container",level:2},{value:"Edit supported Software (Edit a Container)",id:"edit-supported-software-edit-a-container",level:2},{value:"Edit Base Image",id:"edit-base-image",level:2},{value:"Submit Pull Request Instructions",id:"submit-pull-request-instructions",level:2},{value:"1. Before Submitting a Pull Request (PR)",id:"1-before-submitting-a-pull-request-pr",level:3},{value:"2. Submitting a PR",id:"2-submitting-a-pr",level:3},{value:"3. After your PR is merged",id:"3-after-your-pr-is-merged",level:3},{value:"Happy Coding :)",id:"happy-coding-",level:2}];function c(e){const n={a:"a",blockquote:"blockquote",code:"code",em:"em",h2:"h2",h3:"h3",img:"img",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.p,{children:(0,i.jsx)(n.a,{href:"https://gitpod.io/#https://github.com/laradock/laradock",children:(0,i.jsx)(n.img,{src:"https://gitpod.io/button/open-in-gitpod.svg",alt:"Open in Gitpod"})})}),"\n",(0,i.jsx)(n.h2,{id:"have-a-question",children:"Have a Question"}),"\n",(0,i.jsxs)(n.p,{children:["If you have questions about how to use Laradock, please direct your questions to the discussion on ",(0,i.jsx)(n.a,{href:"https://gitter.im/Laradock/laradock",children:"Gitter"}),". If you believe your question could help others, then consider opening an ",(0,i.jsx)(n.a,{href:"https://github.com/laradock/laradock/issues",children:"Issue"})," (it will be labeled as ",(0,i.jsx)(n.code,{children:"Question"}),") And you can still seek help on Gitter for it."]}),"\n",(0,i.jsx)(n.h2,{id:"found-an-issue",children:"Found an Issue"}),"\n",(0,i.jsxs)(n.p,{children:["If you have an issue or you found a typo in the documentation, you can help us by\nopening an ",(0,i.jsx)(n.a,{href:"https://github.com/laradock/laradock/issues",children:"Issue"}),"."]}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Steps to do before opening an Issue:"})}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Before you submit your issue search the archive, maybe your question was already answered couple hours ago (search in the closed Issues as well)."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Decide if the Issue belongs to this project or to ",(0,i.jsx)(n.a,{href:"https://github.com/docker",children:"Docker"})," itself! or even the tool you are using such as Nginx or MongoDB..."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"If your issue appears to be a bug, and hasn't been reported, then open a new issue."}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.em,{children:"This helps us maximize the effort we can spend fixing issues and adding new\nfeatures, by not reporting duplicate issues."})}),"\n",(0,i.jsx)(n.h2,{id:"want-a-feature",children:"Want a Feature"}),"\n",(0,i.jsxs)(n.p,{children:["You can request a new feature by submitting an ",(0,i.jsx)(n.a,{href:"https://github.com/laradock/laradock/issues",children:"Issue"})," (it will be labeled as ",(0,i.jsx)(n.code,{children:"Feature Suggestion"}),"). If you would like to implement a new feature then consider submitting a Pull Request yourself."]}),"\n",(0,i.jsx)(n.h2,{id:"update-the-documentation-site",children:"Update the Documentation (Site)"}),"\n",(0,i.jsxs)(n.p,{children:["Laradock uses ",(0,i.jsx)(n.a,{href:"https://docusaurus.io/",children:"Docusaurus"})," as its documentation site generator."]}),"\n",(0,i.jsxs)(n.p,{children:["Navigate to the ",(0,i.jsx)(n.code,{children:"DOCUMENTATION/docs"})," directory to locate and edit the Markdown files for each section of the documentation."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Note:"})," Each folder under ",(0,i.jsx)(n.code,{children:"docs"})," represents a section in the sidebar menu, with a ",(0,i.jsx)(n.code,{children:"sidebar_position"})," field in the frontmatter of each file that determines its order."]}),"\n",(0,i.jsxs)(n.blockquote,{children:["\n",(0,i.jsxs)(n.p,{children:["The documentation site is auto-generated and deployed to the ",(0,i.jsx)(n.code,{children:"gh-pages"})," branch by GitHub Actions when changes are pushed to the ",(0,i.jsx)(n.code,{children:"master"})," branch."]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"host-the-documentation-locally",children:"Host the Documentation Locally"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["Make your changes are made in the ",(0,i.jsx)(n.code,{children:"DOCUMENTATION/docs"})," directory (if you changed anything)."]}),"\n",(0,i.jsxs)(n.li,{children:["Navigate to ",(0,i.jsx)(n.code,{children:"DOCUMENTATION/"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:["Run the following command to start a local Docusaurus server:","\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:" npm run start\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["Visit ",(0,i.jsx)(n.a,{href:"http://localhost:3000/",children:"http://localhost:3000/"})," to view the documentation site locally."]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"This setup will allow you to preview your changes in real time."}),"\n",(0,i.jsx)(n.h2,{id:"support-new-software-add-new-container",children:"Support new Software (Add new Container)"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Fork the repo and clone the code."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Create folder as the software name (example: ",(0,i.jsx)(n.code,{children:"mysql"})," - ",(0,i.jsx)(n.code,{children:"nginx"}),")."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Add your ",(0,i.jsx)(n.code,{children:"Dockerfile"}),' in the folder "you may add additional files as well".']}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Add the software to the ",(0,i.jsx)(n.code,{children:"docker-compose.yml"})," file."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Make sure you follow the same code/comments style."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Add the environment variables to the ",(0,i.jsx)(n.code,{children:".env.example"})," if you have any."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"MOST IMPORTANTLY"})," update the ",(0,i.jsx)(n.code,{children:"Documentation"}),", add as much information."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Submit a Pull Request, to the ",(0,i.jsx)(n.code,{children:"master"})," branch."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"edit-supported-software-edit-a-container",children:"Edit supported Software (Edit a Container)"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Fork the repo and clone the code."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Open the software (container) folder (example: ",(0,i.jsx)(n.code,{children:"mysql"})," - ",(0,i.jsx)(n.code,{children:"nginx"}),")."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Edit the files."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Make sure to update the ",(0,i.jsx)(n.code,{children:"Documentation"})," in case you made any changes."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Submit a Pull Request, to the ",(0,i.jsx)(n.code,{children:"master"})," branch."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"edit-base-image",children:"Edit Base Image"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Open any dockerfile, copy the base image name (example: ",(0,i.jsx)(n.code,{children:"FROM phusion/baseimage:latest"}),")."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Search for the image in the ",(0,i.jsx)(n.a,{href:"https://hub.docker.com/search/",children:"Docker Hub"})," and find the source.."]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.em,{children:"Most of the image in Laradock are official images, these projects live in other repositories and maintainer by other organizations."})}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Note:"})," Laradock has two base images for (",(0,i.jsx)(n.code,{children:"Workspace"})," and ",(0,i.jsx)(n.code,{children:"php-fpm"}),", mainly made to speed up the build time on your machine."]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Find the dockerfiles, edit them and submit a Pull Request."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["When updating a Laradock base image (",(0,i.jsx)(n.code,{children:"Workspace"})," or ",(0,i.jsx)(n.code,{children:"php-fpm"}),'), ask a project maintainer "Admin" to build a new image after your PR is merged.']}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Note:"})," after the base image is updated, every dockerfile that uses that image, needs to update his base image tag to get the updated code."]}),"\n",(0,i.jsx)("br",{}),"\n",(0,i.jsx)(n.h2,{id:"submit-pull-request-instructions",children:"Submit Pull Request Instructions"}),"\n",(0,i.jsx)(n.h3,{id:"1-before-submitting-a-pull-request-pr",children:"1. Before Submitting a Pull Request (PR)"}),"\n",(0,i.jsx)(n.p,{children:"Always Test everything and make sure its working:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Pull the latest updates (or fork of you don\u2019t have permission)"}),"\n",(0,i.jsxs)(n.li,{children:["Before editing anything:","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Test building the container (docker-compose build --no-cache container-name) build with no cache first."}),"\n",(0,i.jsx)(n.li,{children:"Test running the container with some other containers in real app and see of everything is working fine."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["Now edit the container (edit section by section and test rebuilding the container after every edited section)","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Testing building the container (docker-compose build container-name) with no errors."}),"\n",(0,i.jsx)(n.li,{children:"Test it in a real App if possible."}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"2-submitting-a-pr",children:"2. Submitting a PR"}),"\n",(0,i.jsx)(n.p,{children:"Consider the following guidelines:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Search ",(0,i.jsx)(n.a,{href:"https://github.com/laradock/laradock/pulls",children:"GitHub"})," for an open or closed Pull Request that relates to your submission. You don't want to duplicate efforts."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Make your changes in a new git branch:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-shell",children:"git checkout -b my-fix-branch master\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Commit your changes using a descriptive commit message."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Push your branch to GitHub:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-shell",children:"git push origin my-fix-branch\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["In GitHub, send a pull request to ",(0,i.jsx)(n.code,{children:"laradock:master"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"If we suggest changes then:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Make the required updates."}),"\n",(0,i.jsxs)(n.li,{children:["Commit your changes to your branch (e.g. ",(0,i.jsx)(n.code,{children:"my-fix-branch"}),")."]}),"\n",(0,i.jsx)(n.li,{children:"Push the changes to your GitHub repository (this will update your Pull Request)."}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.blockquote,{children:["\n",(0,i.jsx)(n.p,{children:"If the PR gets too outdated we may ask you to rebase and force push to update the PR:"}),"\n"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-shell",children:"git rebase master -i\ngit push origin my-fix-branch -f\n"})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.em,{children:"WARNING. Squashing or reverting commits and forced push thereafter may remove GitHub comments on code that were previously made by you and others in your commits."})}),"\n",(0,i.jsx)(n.h3,{id:"3-after-your-pr-is-merged",children:"3. After your PR is merged"}),"\n",(0,i.jsx)(n.p,{children:"After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-shell",children:"git push origin --delete my-fix-branch\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Check out the master branch:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-shell",children:"git checkout master -f\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Delete the local branch:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-shell",children:"git branch -D my-fix-branch\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Update your master with the latest upstream version:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-shell",children:"git pull --ff upstream master\n"})}),"\n"]}),"\n"]}),"\n",(0,i.jsx)("br",{}),"\n",(0,i.jsx)(n.h2,{id:"happy-coding-",children:"Happy Coding :)"})]})}function h(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(c,{...e})}):c(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>o,x:()=>l});var i=s(6540);const t={},r=i.createContext(t);function o(e){const n=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:o(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]); |