Merge pull request #143 from brentholtorf/master

Update of Readme and FAQ
microsoft · Oct 26, 2018 · c3b31e2 · c3b31e2
2 parents 2f23104 + e262cf1
commit c3b31e2
Show file tree

Hide file tree

Showing 2 changed files with 90 additions and 10 deletions.
diff --git a/FAQ.md b/FAQ.md
@@ -0,0 +1,63 @@
+# Frequently asked questions
+This topic provides answers to frequently asked questions, and will be updated regularly.
+
+## How do I getting started as a contributer?
+If you're ready to contribute, have a look at the following articles:  
+
+* https://blogs.msdn.microsoft.com/nav/2018/08/28/become-a-contributor-to-business-central/  
+* https://blogs.msdn.microsoft.com/nav/2018/09/20/git-going-with-extensions/  
+
+## Can I contribute by submiting my own app?
+Currently we are accepting code contributions for published apps only.
+
+## Some APIs files aren't available in Extensions V2. What to do?
+Code that relies on temporary files must be rewritten to rely on InStream and OutStream data types instead. Code that relied on permanent files must be rewritten to use another form of permanent storage.
+We are considering a virtualized temporary file system to make it possible to work with temporary files in the cloud at some point in the future.
+
+## DotNet types are not available in Extensions V2. What now?
+SaaS:  
+
+DotNet interop is not available due to safety issues in running arbitrary .NET code on cloud servers. We recommend the following approaches to achieve your business scenario that previously relied on .NET:
+1. With each monthly update we provide new AL types that replace the most typical usages of .NET, such as HTTP, JSON, XML, StringBuilder, Dictionaries and Lists. The new AL types can directly replace many of the .NET usages, which results in much cleaner code. For more information, see [HTTP, JSON, TextBuilder, and XML API Overview](https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-restapi-overview).  
+2. For things you can't do in AL code we recommend using Azure Functions to host the DLL or C# code that was previously embedded in NAV and call that service from AL. To get a more in-depth understanding, check out the following blog posts from our MVPs:  
+
+* [State of .NET Affairs](http://vjeko.com/state-net-affairs/)  
+* [AL support for REST Web Services](http://www.kauffmann.nl/2017/06/24/al-support-for-rest-web-services/)  
+* [Invoking Azure Functions from AL](http://vjeko.com/invoking-azure-functions-al/)  
+
+3. We offer an open source GitHub repository where you can submit .NET type wrappers that, if accepted, will be included in the base application. Here's a link to the repo [C/AL Open Library](https://github.com/Microsoft/cal-open-library).
+
+On-Premise:  
+
+We still encourage you to use the resources above to minimize your reliance on DotNet to make your solutions easily portable to the cloud. However, we are working on adding DotNet interop support to the new development environment, so eventually that will be available.
+
+## Why can't I use the type or method 'XYZ' for 'Extension' development?
+We've blocked a certain set of functions from being directly called from app code. Our approach was based on a conservative static analysis, and the result was that some functions are unnecessarily blocked. If you need to use one or more of these functions please log an issue and provide a full list. We will analyze your request and unblock the functions we deem to be safe.
+
+## Will features from the latest release be back-ported to earlier releases?
+Short answer: Only selected features.  
+
+We have decided to focus our development efforts on a single, latest version of the product. Having said that, we will back-port selected features to the current release on a case-by-case basis. The decision depends on the costs/benefits of doing so and finding a balance between fixing issues that are truly blocking vs. developing new features for the latest version.
+
+## What do all the labels assigned to issues mean?
+We use labels for categorizing issues into types and tracking the issue lifecycle. Issues fall into the following types:  
+
+* Enum-request - request an enum  
+* Request-for-external - request to mark a function as external  
+* Event-request - request for a new event  
+* Extensibility-enhancement - larger suggestion improving extensibility, something we might want to consider in the future  
+
+The lifecycle for issues is (mix of label + milestone + open/closed state):  
+
+* Ships-in-future-update  - the issue was fixed in our source code repository and ships in the next major release
+* Call-for-contributors - we are looking for contributors willing to address reported bug/suggestion
+* Wontfix - the issue will not be fixed probably because it is our of scope of the current repository
+
+## How do I report an issue?
+This GitHub repository is dedicated to handling issues with published apps and extensibility requests for the latest release of Business Central. If you run into an issue, open a support case. You can open Support Request to CSS through PartnerSource portal or contact your Service Account Manager (SAM) in the local subsidiary to understand what is included in your contract as of support incident and PAH (Partner Advisory Hours). Your SAM might also step by step direct you how to open a support request or how to get credentials if this is the first time for you or your company.
+
+## How to I offer a suggestion?
+Similar to the previous question, issues that aren't related to published apps or extensibility are not what this GitHub repository is intended for. In those cases please register your idea in one of the following resources:  
+
+* For functional improvements, go to [Business Central - Ideas](https://experience.dynamics.com/ideas/list/?forum=e288ef32-82ed-e611-8101-5065f38b21f1)  
+* For feature suggestions for AL compiler and developer tools, see [Github.com/Microsoft/AL](https://github.com/Microsoft/AL/issues) for feature suggestions for AL compiler and developer tools  
diff --git a/README.md b/README.md
@@ -1,22 +1,36 @@
 # Microsoft AL application add-on and localization extensions for Microsoft Dynamics 365 Business Central
-The purpose of this repository is to create a collaboration platform between Microsoft and our vibrant partner channel and community for the joint development of application extensions in the AL language.
+Welcome to the ALAppExtension repository!
 
-Going forward, an increasing part of our application business logic will be modularized and extracted into extensions, which will be published onto this repository; this is true for both application add-ons as well as application localizations. The core application thereby becomes thinner, better extensible and better localizable. The extracted modules become open for contributions, are replaceable in the application with substitutes, serve as starting point for verticalizations of the modules or serve as samples for extension development in general.
+This repo is a platform for Microsoft and our vibrant partner channel and community to work together to develop apps in the AL language and enable the general extensibility of Microsoft Dynamics 365 Business Central.
 
-The jointly developed extensions in this repository will be published by Microsoft to App Source and will be shipped with upcoming releases of [Microsoft Dynamics 365 Business Central](https://dynamics.microsoft.com/en-us/business-central).
+We’re working to make the core application thinner, more extensible, and easier to localize by extracting more and more of our application business logic into add-on and localization apps. As we go, we’ll publish the source code for the apps in this repo. The apps are open for contributions and can serve as starting point for verticalizations or just as samples for developing apps.
+
+Microsoft will publish the contributions to the code in this repo on AppSource, and they’ll ship in upcoming releases of [Microsoft Dynamics 365 Business Central](https://dynamics.microsoft.com/en-us/business-central), where you’ll get to enjoy the effect of your contributions.
+
+## Types of engagements
+There are a couple of ways to engage with us here:  
+
+* You can grab the code and contribute to the published apps. For more information, see the _Contributing_ section below.  
+* If you’re building your own app and need something specific from us, like an event, you can help improve the general extensibility of the business logic. For more information, see the _Extensibility requests_ section below.
+
+### Extensibility requests
+The following are the types of requests you can submit to unblock your app:  
+
+* Add new integration events – Get the event you need to hook-in to a process.  
+* Change function visibility – For example, make a public function external or a similar change so you can call it from your extension and reuse the business logic.  
+* Replace Option with Enum – Replace a specific option with an enum that supports your extension. The new type enum is extensible, but all code was written for non-extensible options.  
+* Extensibility enhancements – Request changes in the application code that will improve extensibility.  
+
+We’ll have a look at your request, and if we can we’ll implement it asap. If we can’t we’ll let you know and briefly explain why not. When that happens, don’t be discouraged. Go back to the drawing board, see if you can work it out, and then come back and submit another request.
 
 ## Contributing
-This project welcomes contributions and suggestions.  Most contributions require you to agree to a
-Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
 the rights to use your contribution. For details, visit https://cla.microsoft.com.
 
-When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
-a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
 provided by the bot. You will only need to do this once across all repos using our CLA.
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
-contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
 
 ## How to get started
 1. Become familiar with development in AL. For more information, see https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-get-started.  
@@ -39,3 +53,6 @@ contact [[email protected]](mailto:[email protected]) with any additio
        ```
 5. In Visual Studio Code, connect to your sandbox (follow the steps in the documentation that step 2 refers to) and open the C:\...\C52012DataMigrationReID folder. Now you are ready to go. You can modify the code and build your extension.  
 6. To submit your changes, create a new branch. Remember to revert the change of IDs, and then create a pull request.  
+
+## See Also
+[FAQ](FAQ.md)