Document stories and questions around homepage popular links

docs/homepage.md

@@ -0,0 +1,55 @@
+# Homepage
+
+## Popular Links
+
+Popular links are the links that are present on `gov.uk` under _'Popular on GOV.UK'_.
+These links are maintained through this Mainstream Publisher app.
+
+
+## how to access the page? 
+Popular links can be accessed via homepage on signon.
+
+To be able to access it, we would need 'homepage_editor' permission inside Mainstream Publisher app.
+**_Bit more context on homepage permissions_**:
+Signon by nature expects all the accessible urls to be an app on its own whereas homepage popular links lives 
+inside Mainstream Publisher app and its not a separate app, so the way it works right now is that we have
+a link to homepage on signon generated through running the below command in signon kubernetes
+
+`rake applications:create name=Homepage description="Responsible for creating contents for homepgae" \
+home_uri="https://publisher.integration.publishing.service.gov.uk/homepage/popular-links" 
+redirect_uri="https://publisher.integration.publishing.service.gov.uk/homepage/popular-links/auth/gds/callback"`
+
+though we dont store the secrets generated by running the command anywhere, we just rely on the secrets already configured 
+for Mainstream publisher. This means we can see homepage to appear as an app on signon but its really just a link to access 
+popular links url. This also means that all the permissions related to homepage can only be managed through Mainstream publisher.
+Hence, in order to get access to homepage we need **homepage_editor** permission for the user in Mainstream Publisher
+
+
+# Questions
+Q. Why popular links as an edition?
+A. Not having popular links as an edition would mean having a separate workflow for popular links, 
+   creating a separate workflow just for popular links seemed not necessary at this point in time.
+
+Q. Which schema in publishing api do popular links use?
+A. link_collection
+
+Q. Why popular links as a separate content item instead of moving the whole of homepage to publisher?
+A. Currently our use case is only to allow publishing of popular links and not any other content on the homepage though 
+   in the future we might want to allow other content items as well to be able to publish. Implementation wise, we have 
+   investigated and understood how to allow publishing of popular link as a separate content item and link it to homepage and we 
+   think it is a simple approach to take at this point in time. If we want to allow other content items on the homepage to be 
+   publishable we can still create each of them as a separate content item and publish them separately or move to a strategy of 
+   publishing homepage as a single content item. Though this strategy will require us to investigate more on how that can be done 
+   and understand the complexity and feasibility of it.
+
+Q. Why save and publish for popular links is sync instead of async(sidekiq).
+A. There are few reasons why we chose to keep it sync
+    a. Allows us to give user real feedback in case of publishing api failures
+    b. Allows us to handle and rescue publishing api errors in desired ways. eg: handle 'Cannot publish already published' error to give the user correct feedback.
+    c. Popular links unlike other editions which store them in Artefact stores content-id in PopularLinksEdition, this means we just cant use
+       the current code inside `publish_service.rb` as is to publish popular links as it reads edition's content id from its artefact which basically
+       means we would have to introduce some logic to understand if the edition is PopularLinksEdition or some other edition and based on that read 
+       content id from editions artefact or from PopularLinksEdition itself.
+
+**Worth reading:** [This](https://github.com/alphagov/publishing-api/pull/2750) PR has details of schema and changes made for popular links inside publishing api.
+