-
Notifications
You must be signed in to change notification settings - Fork 259
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Initial creation of tutorials for 3rd party desktop applications #203
base: master
Are you sure you want to change the base?
Conversation
|
||
This will allow the Fedora Workstation Working group to review your application and ask any needed follow-up questions. For more in depth-information about the process and rules for including 3rd party software in Fedora Workstation you can see the [Third Party Software for Fedora](https://fedoraproject.org/wiki/Workstation/Third_party_software_proposal) page. | ||
|
||
[Back to index](how-to-package-a-desktop-application.md) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These back to index
are unnecessary, because there is a link in left panel pointing to that page. This link(ending with .md
) would also most probably not work.
AppStream files allow us to build a modern software center experience either using legacy distro packages with yum-style metadata or with the new flatpak application deployment framework. By including a desktop file and AppData file for your Linux binary build your application can be easily installed by end users. | ||
###Future Work | ||
AppData currently uses the OARS content rating system which will be expanded for more uses cases and filtering options. | ||
### Related Work |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think you have a typo (whitespace) here. I do not know how it would reflect in resulting document.
@@ -0,0 +1,34 @@ | |||
#**Adding Applications to the GNOME Software Center** |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Title is auto-generated.
Have you tested this to see the result? I mean: you can start your local developer-portal instance in vagrant or docker on your computer to see what the web will look like. |
Hi Pavel,
No I haven't tested it, didn't even know we had such docker images
available. I was only told that the agreement that Ryan Lerch and Richard
Hughes had made to get this onto the developer website was that we convert
it to markdown, which is what I did.
Christian
…On Tue, Jun 13, 2017 at 3:44 AM, Pavel Valena ***@***.***> wrote:
Have you tested this to see the result? I mean: you can start your local
developer-portal instance in vagrant or docker on your computer to see what
the web will look like.
—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
<#203 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AUrzSu9p0vVGh5QK_sGgSmM5rGgvWDSuks5sDj3ggaJpZM4N0cVJ>
.
|
Once again: Jekyll headers are missing, thus the pages or any content would not be visible/displayed on the web and thus merging this PR would not yield any result on the Developer Portal.
There is even a Vagrantfile in websites repository. Please make sure the result will be what you actually want before requesting us to accept the changes. Let me know if you run into any issues. |
Sigh, getting something onto the developer site seems rather hard for
someone who is just a causal contributor. It is not clear to me how I get a
link onto the deployment.html page. I tried adding 'jekyll' headers by cut
and pasting the --- section from another document without that seemingly
making a difference for getting the pages onto the website. I am at this
point wondering wether it is better to just post this on the workstation
wiki pages.
Christian
…On Thu, Jun 15, 2017 at 6:49 AM, Pavel Valena ***@***.***> wrote:
Once again: Jekyll headers are missing, thus the pages or any content
would not be visible/displayed on the web and thus merging this PR would
not yield any result on the Developer Portal.
No I haven't tested it, didn't even know we had such docker images
available.
There is even a Vagrantfile in websites repository. Please make sure
<https://github.com/developer-portal/website/blob/master/DEVELOPMENT.md#development>
the result will be what you actually want before requesting us to accept
the changes.
Let me know if you run into any issues.
—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
<#203 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AUrzSkSSaEBhF84mVOs9n3pkfEbxeTMbks5sEQwegaJpZM4N0cVJ>
.
|
So there is an issue with writing the headers? I guess it should be explained better in the contribution guide. On the main page (Order 1) you have to state The content seems cool, so please do not give up on us! Thanks, |
This is tested and builds/renders fine now. There are still some issues I'm working on, like missing images and readability tweaks. But it should work OK now. |
Note that the new section here for desktop deployment requires a graphic in the website static/logo/ folder. I recommend using the graphic at https://people.gnome.org/~engagement/logos/GnomeLogoVertical.svg for this. |
Please create a PR(to websites repo) with addition of that logo in case it does not exist yet. |
Sadly noone got time time to reiew this, including me. To speed this up, please go through the acceptance checklist in issues, as I think at least some of them are still relevant for this PR. |
I believe I've now addressed (if you include the website PR linked above) all the issues, with the possible exception of squashing these commits further. Let me know if that's still an issue. |
Hi @pvalena, could you look at this PR for me? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hello @stickster,
I've gone through your PR and commented on the code directly. I've put only few examples in, as the same issues repeat throughout the PR.
Before you submit more changes, please read through our contributing guide, especially the whole writing section.
Please also do build the site yourself - locally - and check the result looks actually as intended.
Regarding that, if you encounter some issues, you can contact us on our IRC channel #developer-portal on Freenode, as well as on our mailing list.
|
||
# {{page.title}} | ||
|
||
### System Architecture |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You're jumping from level 1 to level 3 title.
MimeType=application/x-openscad; | ||
Categories=Graphics;3DGraphics;Engineering; | ||
Keywords=3d;solid;geometry;csg;model;stl; | ||
Keywords[de]=3D;solid;Geometrie;csg;Modell;stl; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This needs to be in a 'block of code'.
Like this.
<url type="homepage">https://wiki.gnome.org/Apps/MultiWriter</url> | ||
<url type="bugtracker">https://bugzilla.gnome.org/browse.cgi?product=gnome-multi-writer</url> | ||
<translation type="gettext">gnome-multi-writer</translation> | ||
</component> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Definitely needs a block of code.
|
||
If the application is being built on your own machines or cloud instance then the distributor will need to generate the AppStream metadata manually. This would for example be the case when internal-only or closed source software is being either used or produced. This document assumes you are currently building RPM packages and exporting yum-style repository metadata for Fedora or RHEL although the concepts are the same for rpm-on-OpenSuse or deb-on-Ubuntu. | ||
|
||
NOTE: If you are building packages, make sure that there are not two applications installed with one single package. If this is currently the case split up the package so that there are multiple subpackages or mark one of the *.desktop* files as *NoDisplay=true*. Make sure the application-subpackages depend on any *-common* subpackage and deal with upgrades (perhaps using a metapackage) if you’ve shipped the application before. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Above is huge block of text that is on the 4th level of 'nesting' (lvl4 title) and IMHO every reasonable developer will skip this text. Please be more user-friendly! Developer Portal is not site intended for documentation, but for a quick reference! There should be only a link to documentation and few tips, fedora-specific issues etc..
Please check other content on Developer Portal for reference.
1. [Filesystem Hierarchy Standard: 17th October 2016](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard) | ||
2. [Desktop Specification: 17th October 2016](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#introduction) | ||
3. [AppStream Specification 0.10: 17th October 2016](https://www.freedesktop.org/software/appstream/docs/) | ||
4. [SPDX license list](https://spdx.org/licenses/) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No citations needed here. This is not a formal document.
Page should provide only 'handy' links. What user might actually need, to get more information on subject, installation instructions, or github repositories etc..
|
||
You can install appstream-builder in Fedora Workstation by using this command: | ||
|
||
dnf install libappstream-glib-builder |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Needs sudo
and $
and code block again.
git add -A | ||
git commit -a -m "first commit" | ||
git remote add origin git@github.com:yourgitaccount/myrepo.git | ||
git push -u origin master |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please just link to some git guide.
This page should not cover everything.
Such common git instructions would be more suitable for an actual git
section of Developer Portal(there's none so far).
|
||
4. How to [setup and host flatpaks](how-to-setup-and-host-flatpaks.html) | ||
|
||
5. How to [propose third party software for Fedora listing](how-to-propose-a-3rd-party-application-for-inclusion-in-fedora.html) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No overview or content-list please. This should be covered by the side menu itself (i.e. split into multiple pages).
|
||
### Related Work | ||
|
||
The ODRS[1] is a web service which provides end-user moderated application reviews using the AppStream application ID. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Link is missing and I also do not believe this is of any value for developer.
5. How to [propose third party software for Fedora listing](how-to-propose-a-3rd-party-application-for-inclusion-in-fedora.html) | ||
|
||
|
||
### Summary |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do I see correctly there's Introduction
and next's Summary
?
I think you've missed a few. You also need to fullfill all of them (including the squashing) for this PR to be acceptable. |
The file naming also seems somehow redundant. Please drop |
New desktop deployment section
OK, I think the new fixes should be correct. More or less a whole rewrite. I tried to squash down but couldn't avoid the merge I did at cschalle's fork. |
|
||
Metadata for distribution tools and GNOME Software must be refreshed | ||
periodically, such as when new versions of [packaged | ||
applications](desktop-software.html) are released for consumption by |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Where should this link point? I'd say no such path exists. Please use full paths like, f.e. /tech/languages/csharp/csharp-ide.html
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Invariably I missed a couple links while rewriting this heavily. It was a very substantial amount of change.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure, don't worry, we just need those fixed. That's what reviews are for.
|
||
## Generating yum repository metadata | ||
|
||
1. Run these commands to create the initial metadata for source |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why is the numbering here? It's a bit confusing, as the following one is also 1.
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These are steps in a procedure. If it's forbidden to number those, I'll leave them out. But using "1." for each step results in a properly numbered set of steps "1., 2., 3.," etc. without having to renumber manually in the event of a change. Is that not acceptable.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, I did not know that. Does that work with GH-flavored MD? That's what jekyll uses to generate the resuilting website.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see what you mean by steps. However, like I said, this should NOT be a complete guide, thus no steps are needed. You can however outline what's usually done and how, but this web is meant only as a reference pointing to the full-featured guides if needed.
configuration. At this point you can also verify the application | ||
is visible in the *yourcompanyname.xml.gz* file. | ||
|
||
1. Next, take the generated XML and the tarball of icons and add it to |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Here also 1.
. What's the purpose of that?
Writing /tmp/asb-md/appstream.xml.gz... | ||
Writing /tmp/asb-md/appstream-icons.tar.gz... | ||
Writing /tmp/asb-md/appstream-screenshots.tar... | ||
Done! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please do remove the sample output, as someone could accidentally paste it into terminal.
Deploying this metadata allows GNOME Software to add the | ||
application metadata the next time the repository is refreshed. | ||
|
||
## Hosting a DNF repository on Github |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this actually a proper workflow? Do many people host their repository on Github? I'm also not sure this is the correct place to insert guide for git
. Some git section, or external git guide would be better. This is not exactly relevant to the topic.
Note that this shouldn't in any way by a complete
guide, but merely a starting point and links to additional content. We expect the developers do learn themselves.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is also probably not a good idea to tell people to do, since it might not necessarily be something GitHub would appreciate...
For more information on this format, consult the [repository | ||
options in the DNF configuration documentation](http://dnf.readthedocs.io/en/latest/conf_ref.html#repo-options). | ||
|
||
1. Copy this file to */etc/yum.repos.d* on your computer and load up |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Now this is some people would struggle, as you need to use $ sudo
for that and you should include at least some sample command here.
|
||
## Generating Flatpak metadata | ||
|
||
The [Flatpak](https://flatpak.org) application packaging standard is another way to provide metadata for consumers. This guide assumes you are familiar with this standard, along with the [manifest and basic build operations required](http://docs.flatpak.org/en/latest/flatpak-builder.html). You can find extensive information on building Flatpaks and on hosting and signing flatpak repostories [here](https://blogs.gnome.org/alexl/2017/02/10/maintaining-a-flatpak-repository/). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This guide assumes you are familiar with this standard, along with...
Please do remove that sentence, as well as the following one. I do not think it's relevant, but you can include those two links in a reference
section.
Create an empty repository in a *repo* folder with this command: | ||
|
||
```console | ||
$ ostree init --mode=archive-z2 --repo=repo |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this command need an empty directory? Shouldn't there be a command to create it and cd
to it also?
|
||
```console | ||
$ flatpak-builder --verbose --force-clean \ | ||
--repo=repo --gpg-homedir=gpg --gpg-sign=$GPG_KEY \ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Where do I find the $GPG_KEY? Do I leave the variable empty?
your database is up to date. You should then be able to search in | ||
GNOME software and find your new application. | ||
|
||
## Generating Flatpak metadata |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm a bit lost, because there's too much content for one page. This is line 132 and our pages are usually like 40 lines long. It should be just a quick helpful reference, not a full-featured guide.
Flatpack usage does deserve it's own page....
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Relevant issue: #245
Please do work on the content a bit more. I think I did not even get half way through but I think you get the picture. Ref: #203 (comment) |
The required fields are *Name*, *Comment*, *Icon*, *Categories*, | ||
*Keywords*, and *Exec*. Here is an example: | ||
|
||
```console |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is definitely not a console
. You can leave it empty if you cannot decide.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The type is ini
.
|
||
Normally distributions take care of hosting operations from this | ||
point. However, if you want to host your own metadata for use with | ||
yum/DNF or Flatpak, [this guide](hosting-metadata.html) may be of use. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This link is also not pointing anywhere.
I also find this whole block / paragraph useless from developer POV.
Window Sizer* which you installed earlier. To resize the window of | ||
your application to 16:9 format, focus it and press *Ctrl+Alt+s*. | ||
Your application window is resized to a perfect 16:9 aspect ratio | ||
so you can screenshot it with *Alt+PrtScn*. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Likewise I do not think this is a place for a basic usage of any Screenshot
tool. You can link to a relevant guide.
Just a quick check reminds me that I'm repeating myself with directions on how to fix this PR. Please do go through all the comments I've already made and make sure you've somehow incorporated appropriate fix, or please do respond to that comment so we can discuss the issue. Please do not tell me once more you've addressed all the issues, when you in fact didn't. |
Additionally -if you can- please replace the screenshot with some that's of an open-source app. |
Please let me know when you've addressed all issues. |
|
||
## Hosting a Flatpak repository on Github | ||
|
||
Github isn't ideal for hosting Flatpak repositories, but this method currently works. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Again, probably not a good idea...
to provide correct data for your application in this file. Here is | ||
an example for the Frobnicator app: | ||
|
||
```console |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The type is xml
Please give it a look, so we can merge it (it does not have to be perfect, just give it a byte of love). Note: The release will be soon (~1-2weeks), and after that there will be maintenance (decomissioning) of the release infrastucture(no updates for some time). The website updates still need some manual handling, but openshift will change that. |
Updated tutorial to now be split into smaller parts and put them into the deployment substructure as suggested