Skip to content
This repository has been archived by the owner on Oct 2, 2023. It is now read-only.

Latest commit

 

History

History
113 lines (82 loc) · 12.5 KB

CONTRIBUTING.md

File metadata and controls

113 lines (82 loc) · 12.5 KB
Raw

⚠️ Not currently accepting contributions ⚠️

Hello! Welcome to Appstract's contribution guide.

Icons

You're welcome to designs icons for apps you'd like to see supported by Appstract.

Don't know what to add, but want to help? See Appstract's most-requested icons. You'll want to verify that these icons don't already exist - drawable.xml has a list of all icons that have been created. You're also welcome to redesign existing icons if you don't like the way they look, but be aware that redesigns will have to hold up to a higher level of scrutiny than adding new icons.

Color Palette

Design Ethos

  • Keep shapes simple and large
  • Use as few lines as possible
  • When in doubt, prefer simplicity over recognizability

Have a question about any of this or any of your icons, but don't want to open a pull request yet? Head over to Appstract Discussions and post there.

To add new icons to Appstract, follow these steps:

For people who have used Git/GitHub before:

  1. Fork this repository (Github's guide).
  2. Create your icons as svgs in the icons/svgs directory.
    • Refer to the design ethos above in creating your icons.
    • Naming convention: alphanumeric lowercase, separated by underscores where there were spaces (e.g. "Clash Of Clans" becomes clash_of_clans.svg). May not begin with a number.
    • Icons use a document size of 192x192 pixels, and a stroke size of 6px. Feel free to duplicate + rename existing icon files to create your icons, as these should already have these properties set up.
  3. Export the icons as 192x192px .PNGs to the appstract-light folder with black lines, and to the appstract-dark folder with white lines. These should have the same name as the svg (e.g. clash_of_clans.svg -> clash_of_clans.png).
  4. Add the activity names of the icons you've added to app/xml/appfilter.xml. For more information, see Activity Names.
  5. Add yourself to the app/xml/contributors.xml file.
  6. Open a pull request and explain your changes (Github's Guide).

Don't worry about adding your icon to app/xml/drawable.xml; that file is autogenerated based on the appstract-light folder using these scripts I wrote.

For people who haven't used Git/GitHub before:

  1. Follow this guide. It'll tell you to install GitHub Desktop and walk you through the steps of forking a repository and getting it open on your local machine. It assumes that you already have Git installed, so make sure that you've done that before starting the guide. After you read the "Time to do some work" section, come back here.
  2. Open the icons folder using the file explorer, and then open one of the template icons in the svgs folder using your preferred editing software (Inkscape, Illustrator, or similar). Use Save As to save the file with a new name, separated by underscores where there were spaces (e.g. "Clash Of Clans" becomes clash_of_clans.svg). The file name cannot start with a number (if the original one does, do something like "9gag" -> nine_gag.svg). Again, this should create a new file separate from those that already exist, not overwrite/delete any of the existing ones (unless you are redesigning an icon). Then, design your icon!
    • Refer to the design ethos above in creating your icons.
    • Icons use a document size of 192x192 pixels, and a stroke size of 6px.
  3. Export the icons as 192x192px .PNGs to the appstract-light folder with black lines, and to the appstract-dark folder with white lines. At no point should you delete or replace any of the existing icons unless you are redesigning an icon.
  4. Add the activity names of the icons you've added to app/xml/appfilter.xml. For more information, see Activity Names.
  5. Add yourself to the app/xml/contributors.xml file.
  6. "Commit" your changes (mark them as a finished step in Git's history). See step: "Commit your Changes".
    • Before committing, you should check that you have exactly n changes, where n = (number of icons you made * 3) + 2, since you added three files for each new icon added, plus the two text files (steps 4 and 5).
    • If you only added new icons, you should only see next to your icon files. If you redesigned an icon, you'll probably see for those icons. You'll also see the modified symbol for the two text files. Except in rare cases, you shouldn't see any - if you do (and it wasn't intentional), just uncheck those changes, as demonstrated in the above image. This will prevent those deletions from being recorded as "history". If all else fails and you can't figure out how to fix your changes, (or you already committed), feel free to continue to the next steps and make a note in your PR that you need help cleaning up your commits. I have write access to most forks and can help :)
  7. "Push" your commit to your "fork" (sync your changes with the repository under your account). See step: "Push your Changes".
  8. Open a "pull request" (a request to add your changes back to this repository). See step: "Submit your PR". Here, you might get some errors that look like the below image. This is expected - the repository is running a series of automated checks against your changes, to make sure that they conform to the expected format. If you get any, you can click "Details" on the failing check and it should tell you exactly what isn't looking as expected. If you make a new commit that fixes the problem, then the check will start passing. Once you've opened the PR, you might see a button that says "Comment and Close". Closing the PR means that you don't want me to look at your changes anymore. Make sure you don't press the "Comment and Close" button unless that's what you want to happen; use the "Comment" button instead.
  9. Once I approve the icons, I'll merge the pull request (add your changes to the main repository).

If at any point you're having trouble with any of the steps, feel free to reach out to me at mirrorkeydev@gmail.com :)

Activity Names

Activity names look like this:

  • com.dkanada.icecons/com.dkanada.icecons.MainActivity
  • cn.nubia.gallery3d/cn.nubia.gallery3d.app.Gallery
  • com.rayark.valkyrie/com.onevcat.uniwebview.AndroidPlugin

An icon must always have at least one activity name associated with it. Generic apps tend to have lots of these, while lesser-known apps will generally only have one or two.

Finding activity names for your icon

  • If your icon is in the list of most-requested icons, you should be able to find activity names there.
  • Use iconpusher.com to search for your app. Make sure you use entries from the appfilter.xml section, not the appmap.xml.
  • Download an app such as Package Name Viewer or Turtl to view activity names for apps on your personal device. Note that the app might show you two smaller names, such as uk.co.aifactory.chessfree and uk.co.aifactory.chessfree.ChessFreeActivity; these are to be combined with a / between them, like so: uk.co.aifactory.chessfree/uk.co.aifactory.chessfree.ChessFreeActivity.
  • Google "ComponentInfo" [name of app] "appfilter.xml" (with the "s) - there you should find other appfilter.xml files, with the corresponding activity names there.
  • Google hybrid analysis [name of large icon pack, such as Linebit, Crayon, etc.]. Go to the page matching something like Linebit_1.4.6.apk - Hybrid Analysis, and scroll down to the Extracted Strings section. Search for your icon (e.g. clash_of_clans), and there you'll find full activity names.

Adding activity names to appfilter.xml

An appfilter.xml entry for an icon looks like this:

<!---google_earth-->
<item component="ComponentInfo{com.google.earth/com.google.android.apps.earth.EarthActivity}" drawable="google_earth"/>
<item component="ComponentInfo{com.google.earth/com.google.earth.EarthActivity}" drawable="google_earth"/>

The activity name goes between the curly braces in "ComponentInfo{}". The icon file name (without .svg or .png) goes between the double quotes in drawable="". For every activity name, a new <item component="ComponentInfo{ ... }" drawable=""/> line is added beneath others.

Important: before you add a new activity name to appfilter.xml, do a ctrl-f and search for your icon - it's possible that a section for your icon already exists. If that's the case, just modify that section to match your icon file name and add any new activity names not already in that section. If you don't check for existing sections before adding a new one, your icons might not apply correctly.

Documentation

Any of these instructions seem unclear? Think the README needs a new section? Found a typo?

Feel free to make changes to documentation files. If you want to propose a large, restructuring change to these docs, or even just discuss a smaller one, feel free to head over to Appstract Discussions and post there.

Actions/Workflows

If you'd like to contribute to the web of tiny GitHub workflows that run against new PRs, feel free to do so :)

Ideas:

  • A workflow that checks that all lines in the svgs provided are 6px wide. (I've tried to do this, turns out that vector matrix transformation stuff makes it hard to tell what a line width is just based on the svg xml. It'll say 16.299382 in the file and I'll open it in Inkscape and it'll be 6px)
  • A workflow that ensures that lines are always round-capped and black or white
  • A workflow that analyzes the colors in the svg and ensures that they fall into certain ranges based on the design ethos color palette
  • A workflow that checks that filenames in appfilter.xml actually match the names of files submitted
  • A workflow that checks that there aren't more than 4 colors in a given icon.

Code

I don't have any plans for code changes - Appstract is currently built on Sarsa Murmu's maintained Candybar fork: zixpo/candybar-sample. If you want to contribute to that, head over to his repo :)

Disclaimer

By contributing to this repository, you agree to have your work bound to the repository's license.