We are beyond excited that you want to contribute! We would love to accept your contributions. Pieces Open Source is built for the community and warmly welcomes collaboration. There are many ways in which one could contribute to Pieces Open Source, and every contribution is equally appreciated here. Navigate through the following to understand more about contributing.
Firstly, thank you for considering contributing to Pieces Open Source. This guide details the general information that one should know before contributing to the repository. Please stick as closely as possible to the guidelines. That way, we ensure that you have a smooth experience contributing to this project.
If you are a designer - start here to get more specific information.
These are, in general, rules that you should be following while contributing to an Open-Source Pieces project:
- Be Nice, Be Respectful (BNBR)
- Check if the Issue you created already exists or not
- When creating a new issue, make sure you describe the issue clearly
- Use tags to mark your issue as “draft” (we will remove the draft tag once we assign the proper issue tags to the created issue)
- Make proper commit messages and document your PR well
- Always add comments to your code
- Follow proper code conventions because writing clean code is important
- Add @jordan-pieces as a reviewer to be assigned to another maintainer or to be reviewed
- Issues will be assigned on a "First Come, First Served" basis
- Once an issue has been assigned, if we don’t receive any reply/response in a week, we will reassign the issue to someone else and remove the assignee
- Do mention (@jordan-pieces) the project maintainer if your PR isn't reviewed within three days
-
Ensure you have the latest version of Pieces OS installed on your system:
-
Ensure that you have NPM installed.
To ensure consistent code formatting across the project, we've integrated Prettier into our workflow. You can find more details about Prettier Here.
1. Configuration
We've included a .prettierrc file at the root of the project with the following configuration:
{
"semi": true,
"singleQuote": true,
"trailingComma": "es5",
"printWidth": 80,
"tabWidth": 2,
"bracketSpacing": true
}This will enforce consistent code formatting rules across the project, including semicolons, single quotes, trailing commas, line width, tab spacing, and bracket spacing.
2. Scripts in package.json
We've added the following scripts in package.json:
{
"scripts": {
"format": "prettier --write \"src/**/*.{js,jsx,ts,tsx,json,css,scss,md}\"",
"format:check": "prettier --check \"src/**/*.{js,jsx,ts,tsx,json,css,scss,md}\""
}
}These scripts automate code formatting (format) and checking (format:check) for JavaScript, TypeScript, JSX, JSON, CSS, SCSS, and Markdown files within the src directory.
3. Check Formatting
To verify code formatting without making any changes, run:
npm run format:check4. Format Code
To format your code automatically, use the following npm script:
npm run formatThese configurations automate code formatting and ensure consistent style across the project.
1. Fork the repository on GitHub.
2. Clone the forked repository. Open up the GitBash/Command Line and type:
git clone https://github.com/<YOUR_USER_NAME>/<FORKED_REPO_NAME>.git3. Navigate to the project directory:
cd <FORKED_REPO_NAME>4. Add a reference to the original repository:
git remote add upstream https://github.com/pieces-app/example-typescript.git5. See the latest changes to the repo using:
git remote -v6. Create a new branch:
git checkout -b <YOUR_BRANCH_NAME>7. Always take a pull from the upstream repository to your main branch to keep it even with the main project. This will save you from frequent merge conflicts:
git pull upstream main8. You can make the required changes now. Make appropriate commits with proper commit messages.
9. Add and then commit your changes:
git add . && git commit -m "YOUR_COMMIT_MESSAGE"10. Push your local branch to the remote repository:
git push -u origin <YOUR_BRANCH_NAME>11. Once you have pushed the changes to your repository, go to your forked repository. Click on the Compare & pull request button.
12. Give a proper title to your PR and describe the changes you made in the description box. (Note: Sometimes there are PR templates that are to be filled in as instructed.)
13. Open a pull request by clicking the Create pull request button.
Voila, you have made your first contribution to this project
Issues can be used to keep track of bugs, enhancements, or other requests. Creating an issue to let the project maintainers know about the changes you are planning to make before raising a PR is a good open-source practice.
Let's walk through the steps to create an issue:
1. On GitHub, navigate to the main page of the repository. Here in this case.
2. Under your repository name, click on the Issues button.
3. Click on the New issue button.
4. Select one of the Issue Templates to get started.
5. Fill in the appropriate Title and Issue description and click on Submit new issue.
We also have opportunities to contribute to our projects as a designer and to submit your design mockups kindly upload them as PDFs to the /drafts directory. Follow along with the below guide to get started:
Your creativity is truly appreciated! We have set up some simple folders where you can upload drafts and design files for review, and usage during development.
Check out these steps for uploading a pdf export into the /mockups folder:
- Export your file from your design software as a .PDF file
- After you have followed the above steps to fork the repo and download the project, open up the
/mockupsfolder and locate either draft or final depending on your current status - Then save the PDF to one of the directories, and set the title in this pattern:
- [date][pagename][authorname].pdf
- Then commit your changes to your local branch, push those change and open up a PR! From there you should be all good to go.