-
Notifications
You must be signed in to change notification settings - Fork 363
contributing new part process
Here is a start for documentation on the process for contributing to the fritzing/fritzing-parts repository on github. This shows how (one way) to get new and changed files to where they can be added to the main parts library used by Fritzing. I suggest reading it all through (at least) once, then come back to beginning to start doing it. For the rules, and how to create and modify those files, see other documentation.
Here are a few places to look to learn more about part creation. A lot of it is outdated, but at least it is a place to start.
- creating custom parts — providing part graphics
- make your own Fritzing parts
- making a part in Fritzing 0.8.7b
- 2.1 part file format
- Part Creation Howto: Part 1, Breadboard and PCB
- search the forum posts (magnifying glass icon) for
parts howto
Now for the process around getting the part information where it can be used. At a high level, the steps are:
- create your own copy (fork) of the [fritzing/fritzing-parts repository](fritzing/fritzing-parts repository) where the parts live, that Fritzing expects to use.
- get a copy (clone) of the fork onto your local machine
- create and modify parts in that local copy
- send the updates back to your fork
- send a request to the repository maintainers to add your updates to fritzing/fritzing-parts, where the Fritzing application can find and get access to them.
In the following details, many of the command steps can be shortened, or entirely skipped, if you know the current environment state, and the git commands well enough. I have tried to use commands that avoid assumptions about the current state.
Need a github account
Breaking that down, creating the fork starts with having a github account. Running the Fritzing application does not needed an account. The parts database can be read and downloaded from github without an account. But to create a fork, or send the request to add your updates, needs an account. Start at the github home page and sign up. There are other tutorials for working with github. I am not going to try to duplicate or replace them here. But here is a link that does a web search that provides places to start. If all you are using github for is sending updates to the fritzing parts library, most of that can be skipped. The minimal details needed will be provided here.
With a github github account, login, then go to the Fritzing Parts library repository.
Github has tools to help locate repos you might be interested in. Putting "fritzing parts" in the search requester currently returns 181 repository results. The link I provided above is the same as (currently) the first one in those results, which is the one of interest here. That is fritzing/fritzing-parts the rest are libraries and parts collections created by other people (Adafruit, Sparkfun), and (most of) the rest are forks of one of those libraries.
At the top of the fritzing/fritzing-parts page, just below the github control and navigation bar, is a line that starts on the left with
The right end of that line has a button with a "Y" ish looking symbol labelled "Fork", and a number after it. The number is a count of the number of forks of the repository that currently exist (on github). We are going to make that number one bigger. Click the Fork button. In the normal case, that should show a page saying that forking is in progress, then go the page for your fresh fork of that repository. The top line will now show "«yourUserName» / fritzing-parts".
That is all that really needs to be done on github. You could log out and close the browser page. The next steps are done from your local machine. You will need the user account and password later, to send your awesome parts back to github. It is convenient to have the browser page open to the forked repository, because it provides a quick way to get the url string needed when cloning.
A git client will be needed on your machine, to access the content on github, and send changes back. There are multiple options, and variations for different operating systems. This is not about installing git, so I am not going to try to provide details here. This documentation assumes working with a basic command line version of git. The link above points to the main git page as a place to start. Web searches for "install git" plus your operating system (windows, mac, linux) should provide the needed details. If unsure, this is probably the place to start. Get git installed before bothering to create a github account.
A little configuration is needed, so that git knows how to present you for some commands, and how to ask for information when needed. Getting Started - First-Time Git Setup has the general commands and descriptions needed. The editor does not need to be set, if the one line commit command described here is always used. But to have multiple lines in the commit message, the editor is needed too. The last configuration in the list, for push.default, is not included on the reference page. I use it because it makes my documented push workflow simpler. The setting is actually the default, but this makes sure that the git commands only work on one branch at a time, unless options (not described here) are added.
git config --global user.name "The Name You Want to be Known By"
git config --global user.email [email protected]
git config --global core.editor «yourEditorPreference --andStartupParameters»
git config --global push.default simpleWith git installed, open a command line (cli) window, and change the directory to where the project folder (or folders) for the Fritzing parts is to be created. As a quick check, type
git --versionto make sure that git is installed and running from your cli window. Mine currently shows git version 2.24.1 Some installations (on windows) need to have the cli windows opened a special way before git can be used. I am not going to get into all of the git version differences and problems over time. This assumes using a sufficiently recent version.
Type "git clone " followed by the url for your forked fritzing-parts repository on github, followed by "--branch develop". This is where the browser window comes in handy. A few lines down, on the right hand side, is a green drop down button that says "Clone or download". Clicking that opens a widget that should say "Clone with HTTPS". Clicking the clipboard icon copies the path to the repository into your operating system clipboard buffer. So the easy way to do this is:
- type 'git clone ` «including the space at the end»
- click "Clone or download", then click the clipboard icon
- paste into the cli window
- type ' --branch develop'
- press enter (or return)
The method to paste to a cli windows varies depending on operating system, and a few other variations, but in most cases, right click (cmd click on mac) in the window brings up a context menu with a paste option.
The whole thing can also be typed in manually. It looks like:
git clone https://github.com/«yourUserName»/fritzing-parts.git --branch developThat will create a folder named "fritzing-parts" within the current folder for the cli window, and copy the parts information from the develop branch on github into it. It shows progress information as it goes, but within a minute or 2 (depending on Internet connection speed) should end up with something like:
Cloning into 'fritzing-parts'...
remote: Enumerating objects: 94, done.
remote: Counting objects: 100% (94/94), done.
remote: Compressing objects: 100% (59/59), done.
remote: Total 18416 (delta 53), reused 52 (delta 35), pack-reused 18322
Receiving objects: 100% (18416/18416), 138.62 MiB | 3.39 MiB/s, done.
Resolving deltas: 100% (12770/12770), done.
The actual numbers will change, depending on what changes have already been done to the repository since the example was created. It could also vary some depending on the version of git being used.
The "--branch develop" at the end is not part of the default clone command. But it makes the branch that is needed for parts creation immediately available locally.
Move into the fritzing-parts folder with the cli (cd fritzing-parts). This is where most (probably all) of the git commands will be run, to manage created part files, and get updates from (synchronize with) the fritzing/fritzing-parts repository. That is needed, because at various times, the latest information that has been added by other people could be wanted. This folder is where you can point the Fritzing app, to reference the parts stored here. Your own, the ones initially forked and cloned, and any added (or changed) that have been synchronized. Telling Fritzing to use this folder as the parts library is the usual (easy) way to test your creations. This documentation is not about that process, so I'll just say that with recent versions of Fritzing, starting the application from the command line, with something like
fritzing --parts "/path/to/your/fritzing-parts"gets started. Probably also need to regenerate the parts database to get it to properly see either your or the synchronized changes. Fritzing is going to see the parts that are in the currently active branch. The one that has been checked out, which is what git status will report.
When initially cloned, the local git repository only knows about its own content, and its "origin", which is your forked repository on github. It does not know anything about where the fork was created from. That means it has no way to synchronize with changes done there. The forked repository and github can not do it directly either. To change that, we can tell git where an additional repository exists, which means git commands can use it. Move into the fritzing-parts folder in a cli window.
git remote -vShould currently show 2 lines. Both of them for "origin" with the url that the local repo was cloned from. Your forked repo on github. To tell the local repo about fritzing/fritzing-parts, typically called "upstream" (the parent of the origin), enter
git remote add upstream https://github.com/fritzing/fritzing-partsNow git remote -v should show an extra 2 lines
upstream https://github.com/fritzing/fritzing-parts (fetch)
upstream https://github.com/fritzing/fritzing-parts (push)
and git commands can reference the content using "upstream".
To gather a bit of extra information locally, also do
git fetch upstream
git fetch upstream --tagsThat is the end of the one time preparation. Following command sequences are used each time a new parts project is started.
Each time a new branch is created, for a new part creation project, it is a good idea to first synchronize the local develop branch with upstream. That can avoid extra work, by you or the maintainers, when it is time to create the pull request.
git checkout develop
git merge upstream/developIf there are no changes to the develop branch in fritzing/frizting-parts, since the fork and clone, or since the previous synchronize, the merge will just report "Already up to date." When there is something that can be merged (synchronized), the command will provide some details. If a merge is not "Already up to date.", then optionally
git pushcan be run. That sends the synchronized branch to your forked copy of the repo. This is optional, because the new branch creation is going to be based on the local develop branch. It does not hurt to push, and can be useful if the forked repo is going to be cloned someplace else. It will keep the branch on the forked repo synchronized with upstream, in addition to the local branch.
With the local develop branch synchronized with upstream, it can be used to create a clean new working branch for the planned project.
git checkout -b «projectBranchName» developThat creates a local "«projectBranchName»" branch based on the current contents of the local develop branch. The environment is now ready to accept your new parts. Content can be moved or copied into the appropriate sub folders, or created and edited there directly. Once (supposedly) ready, Fritzing can be run using the repository folder as the parts library folder for testing. Other tools, like the FritzingCheckPart, can be used to help testing as well, but that (at least the current version) really needs to be done outside of the fritzing-parts folder. The standard edit, test, loop process.
So the parts are perfect now. Testing is done, and no problems found. We hope. Now it is time to get those changes on the way to where everyone can use them. The first step in that, is to get the changed files added and committed to the local working git project branch. But are they really the files you expect?
git statusShows information about the currently active branch. The name of the branch, whether it is up to date with the (linked) remote repos, which files are waiting to be committed, which have been create but not yet added to the branch, which have been modified or moved. If doing just what is being described here, there should (only) be "untracked" files for all of your new fzp and svg files, plus renamed svg files moved to obsolete, plus modified files for the fzp files that were moved to obsolete. Anything else is cause for having a close look, and possible clean-up before proceeding. Once git status shows all, and only, the files expected for the project:
git add --all
git commit --message "description of what changes are added by this commit"
git pushThat adds all of the changes that git status showed to the "staging area" of the branch, then "commits" (saves) them (permanently) to the branch, and finally sends the updated branch to your forked repository on github. That is going to need your github account user name and password.
Your creation is now sitting in a branch on your forked repo on github. But fritzing/fritzing-parts does not know anything about it yet. You need to tell upstream to look at it, and ask to have it added to the fritzing/fritzing-parts repo. That is done using a pull request.
Login to github, and go to the page for your forked fritzing-parts repository. That will be a url like "https://github.com/«YourUserName»/fritzing-parts". A few lines down from the top is line with "Branch: «some_name»" "New pull request". Click the branch drop down, and select «projectBranchName». Then click the "New Pull request" button. The git push command also probably reported the url to the pull request page, so that could have just been copied and pasted after logging in to github.
All of the fields should already be filled in correctly here, but make sure. The "base repository" should be "fritzing/fritzing-parts". The base is "develop". The head repository is your fork, "«YourUserName»/fritzing-parts", and compare is «projectBranchName». Fill in some description information, so the maintainers have some idea about what changes will be added, and why, then send it off. And wait. The maintainers need to get the request, review it, decide if it can be accepted as is, maybe do some of their own testing, or request more information or changes first. Unless a lot of things (on github) have been disabled, you should get email notifications about what is happening. You get the notifications faster if you stay logged in to github.
Depending what they ask, you might need to use more git commands. I am not (at least yet) going to try to anticipate what that might be. Do some reading, and ask for help when that happens. That is not part of the main flow being documenting here.
Your pull request has been accepted and implemented. Your parts are now in the "develop" branch of "fritzing/fritzing-parts" Users of the Fritzing app can not see them yet. That has to wait until the maintainers merge develop changes into master. But that is out of your hands now. A synchronization with the upstream develop branch brings your parts, and possibly others, into your local develop branch. That can be a final check before deleting the working project branch, and create a new one for the next project.
git checkout develop
git merge upstream/develop
git log --onelineThe "log" command shows a little information about the recent commits to the branch. Since that was just merged with upstream, it has all of the latest changes. You should be able to find the message for your commit in the top few lines. If there were a lot of commits at the same time, the message might be further down. If you can't see it, try again without the "--oneline" option. That shows more information, including the Author (hey, that's you, the name and email address you configured for git), and date. That is in date order by when the commit was done, not when the pull request was created, or accepted. So scan through it, until you get to a date before you did the commit. If you still can find it, ask if the PR actually got merged.
Everything can be found where it belongs. In upstream. The «projectBranchName» branch, both locally and in the forked repo are now redundant. All of the information they contain is now in upstream/develop. To clean-up, those should be deleted.
git checkout develop
git push origin --delete «projectBranchName»
git branch -d «projectBranchName»The local clone is now "clean" again. Ready to start your next part creation (ad)venture. You do not need to wait until here to start another project. Once the commit is done for one branch, another working branch can be created and used in the same repository clone. It does become more of a hassle though to switch back to that branch once edits have been done in the new one. A different branch can not be checked out while there are uncommitted edits in the current one. Which means committing the work in progress, stashing it, or cloning a new copy of the repo to get access to the other branch. All of which is outside of the scope of the current document.
Once you have a feel for the process, this section provides a summary showing the commands needed at each stage. Use it as a quick reference, to see the commands need for the current stage of your project.
One time only steps
- create github account
- fork fritzing/fritzing-parts repository
- install git cli client
git clone https://github.com/«yourUserName»/fritzing-parts.git --branch develop
git config --global user.name "The Name You Want to be Known By"
git config --global user.email [email protected]
git config --global core.editor «yourEditorPreference --andStartupParameters»
git config --global push.default simple
git remote add upstream https://github.com/fritzing/fritzing-parts
git fetch upstream
git fetch upstream --tagsFor each new project
git checkout develop
git merge upstream/develop
git checkout -b «projectBranchName» developdo some work, do some testing
git status
git add -all
git commit --message "description of what changes are added by this commit"
git pushCreate the pull request, and follow through on that
git checkout develop
git merge upstream/develop
git log --oneline
git push origin --delete «projectBranchName»
git branch --delete «projectBranchName»Here are a couple of web search links to learn more about using git and github
The git scm web site has a documentation section with resources for more in depth and focused learning.
Since this is a Fritzing specific reference area, I'll mention that Sparkfun has a Using github tutorial.
Post questions or suggestions to the issues section of the fritzing-parts repository, or to the Fritzing forum. You can get to the issues through the "Issues" link at the top of this (or any other fritzing-parts wiki) page. Posting to issues needs a github account, the forum needs a Fritzing site account.