Skip to content
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

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

cschalle
Copy link

@cschalle cschalle commented Jun 8, 2017

Updated tutorial to now be split into smaller parts and put them into the deployment substructure as suggested


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)
Copy link
Contributor

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
Copy link
Contributor

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**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Title is auto-generated.

@pvalena
Copy link
Contributor

pvalena commented Jun 13, 2017

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.

@cschalle
Copy link
Author

cschalle commented Jun 13, 2017 via email

@pvalena
Copy link
Contributor

pvalena commented Jun 15, 2017

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 the result will be what you actually want before requesting us to accept the changes.

Let me know if you run into any issues.

@cschalle
Copy link
Author

cschalle commented Jun 15, 2017 via email

@pvalena
Copy link
Contributor

pvalena commented Jun 22, 2017

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.

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 section: deployment in the jekyll header(example) and the subsection name has to be unique in the section. Well any minor issues we can fix later on, but it should at least work.
Please also push your changes(even WIP) to your github fork (no need to close this PR; and you can do git push --force if you need to) so I can see the changes. Let me know, ideally on irc, if I can be of any help.

The content seems cool, so please do not give up on us!

Thanks,
Pavel

@stickster
Copy link

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.

@stickster
Copy link

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.

@pvalena
Copy link
Contributor

pvalena commented Jul 13, 2017

Note that the new section here for desktop deployment requires a graphic in the website static/logo/ folder.

Please create a PR(to websites repo) with addition of that logo in case it does not exist yet.

@pvalena
Copy link
Contributor

pvalena commented Aug 28, 2017

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.

@stickster
Copy link

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.

@stickster
Copy link

Hi @pvalena, could you look at this PR for me?

Copy link
Contributor

@pvalena pvalena left a 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
Copy link
Contributor

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;
Copy link
Contributor

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>
Copy link
Contributor

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.
Copy link
Contributor

@pvalena pvalena Oct 30, 2017

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/)
Copy link
Contributor

@pvalena pvalena Oct 30, 2017

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
Copy link
Contributor

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
Copy link
Contributor

@pvalena pvalena Oct 30, 2017

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)
Copy link
Contributor

@pvalena pvalena Oct 30, 2017

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.
Copy link
Contributor

@pvalena pvalena Oct 30, 2017

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
Copy link
Contributor

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?

@pvalena
Copy link
Contributor

pvalena commented Oct 30, 2017

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.

I think you've missed a few. You also need to fullfill all of them (including the squashing) for this PR to be acceptable.

@pvalena
Copy link
Contributor

pvalena commented Oct 30, 2017

The file naming also seems somehow redundant. Please drop desktop from the prefix, as you're already in desktop subsection. And also please do not prefix files with how-to-.

@stickster
Copy link

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
Copy link
Contributor

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.

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.

Copy link
Contributor

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
Copy link
Contributor

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..

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.

Copy link
Contributor

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.

Copy link
Contributor

@pvalena pvalena Jan 23, 2018

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
Copy link
Contributor

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!
Copy link
Contributor

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
Copy link
Contributor

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.

Copy link
Contributor

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
Copy link
Contributor

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/).
Copy link
Contributor

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
Copy link
Contributor

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 \
Copy link
Contributor

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
Copy link
Contributor

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....

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Relevant issue: #245

@pvalena
Copy link
Contributor

pvalena commented Jan 23, 2018

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
Copy link
Contributor

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.

Copy link
Contributor

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.
Copy link
Contributor

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*.
Copy link
Contributor

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.

@pvalena
Copy link
Contributor

pvalena commented Jan 23, 2018

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.

@pvalena
Copy link
Contributor

pvalena commented Jan 23, 2018

Additionally -if you can- please replace the screenshot with some that's of an open-source app. Steam does not look like a right choice from Fedora POV.

@pvalena
Copy link
Contributor

pvalena commented Feb 2, 2018

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.
Copy link
Contributor

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The type is xml

@pvalena
Copy link
Contributor

pvalena commented Feb 14, 2020

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants