You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by GitBox <gi...@apache.org> on 2018/01/24 08:09:54 UTC
[GitHub] aditihilbert closed pull request #758: Deleting repo from tutorials dir from mynewt-core
aditihilbert closed pull request #758: Deleting repo from tutorials dir from mynewt-core
URL: https://github.com/apache/mynewt-core/pull/758
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/os/tutorials/repo/add_repos.rst b/docs/os/tutorials/repo/add_repos.rst
deleted file mode 100644
index 99a20a585..000000000
--- a/docs/os/tutorials/repo/add_repos.rst
+++ /dev/null
@@ -1,331 +0,0 @@
-Adding Repositories to your Project
-===================================
-
-.. toctree::
- :hidden:
-
- create_repo
- private_repo
- upgrade_repo
-
-
-What is a Repository
-~~~~~~~~~~~~~~~~~~~~
-
-A repository is a version-ed Mynewt project, which is a collection of
-Mynewt packages organized in a specific way for redistribution.
-
-What differentiates a repository from a Mynewt project is the presence
-of a ``repository.yml`` file describing the repository. This will be
-described below. For a basic understanding of repositories you may read
-the `Newt Tool Manual <../../../newt/newt_intro.html>`__ and `How to
-create repos <create_repo.html>`__.
-
-**Note:** For the remainder of this document we'll use the term repo as
-shorthand for a Mynewt repository.
-
-Repos are useful because they are an organized way for the community to
-share Mynewt packages and projects. In fact, the Mynewt-core is
-distributed as a repo.
-
-Why does Mynewt need additional repos?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Repos add functionality not included in the Mynewt core. New repos might
-be created for several reasons.
-
-- **Expertise**. Individuals or organizations may have expertise that
- they want to share in the form of repos. For example a chip vendor
- may create a repo to hold the Mynewt support for their chips.
-- **Non-Core component**. Some components, although very useful to
- Mynewt users are not core to all Mynewt users. These are likely
- candidates to be held in different repos.
-- **Software licensing**. Some software have licenses that make them
- incompatible with the ASF (Apache Software Foundation) license
- policies. These may be valuable components to some Mynewt users, but
- cannot be contained in the ``apache-Mynewt-core``.
-
-What Repos are in my Project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The list of repos used by your project are contained within the
-``project.yml`` file. An example can be seen by creating a new project:
-
-.. code-block:: console
-
- $ mkdir ~/dev
- $ cd ~/dev
- $ newt new myproj
- $ cd myproj
-
-View the ``project.yml`` section and you will see a line describing the
-repos:
-
-.. code-block:: console
-
- project.repositories:
- - apache-Mynewt-core
-
-By default, this newly created project uses a single repo called
-``apache-Mynewt-core``.
-
-If you wish to add additional repos, you would add additional lines to
-the ``project.repositories`` variable like this.
-
-.. code:: hl_lines="3"
-
- project.repositories:
- - apache-Mynewt-core
- - another_repo_named_x
-
-Repo Descriptors
-~~~~~~~~~~~~~~~~
-
-In addition to the repo name, the ``project.yml`` file must also contain
-a repo descriptor for each repository you include that gives ``newt``
-information on obtaining the repo.
-
-In the same ``myproj`` above you will see the following repo descriptor.
-
-.. code-block:: console
-
- repository.apache-Mynewt-core:
- type: github
- vers: 1-latest
- user: apache
- repo: mynewt-core
-
-A repo descriptor starts with ``repository.<name>.``. In this example,
-the descriptor specifies the information for the ``apache-Mynewt-core``.
-
-The fields within the descriptor have the following definitions:
-
-- **type** -- The type of code storage the repo uses. The current
- version of ``newt`` only supports github. Future versions may support
- generic git or other code storage mechanisms.
-
-- **vers** -- The version of the repo to use for your project. A source
- code repository contains many versions of the source. This field is
- used to specify the one to use for this project. See the section on
- versions below for a detailed description of the format of this
- field.
-
-- **user** -- The username for the repo. On github, this is the name
- after ``github.com`` in the repo path. Consider the repository
- ``https://github.com/apache/mynewt-core``. It has username
- ``apache``.
-
-- **repo** -- The name of the repo. On github, this is the name after
- the username described above. Consider the repository
- ``https://github.com/apache/mynewt-core``. It has path
- ``mynewt-core``. This is a path to the source control and should not
- be confused with the name of the repo that you used in the
- ``repository.<name>`` declaration above. That name is contained
- elsewhere within the repo. See Below.
-
-Adding Existing Repos to my Project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To add a new repo to your project, you have to complete two steps.
-
-- Edit the ``project.yml`` file and add a new repo descriptor. The
- previous section includes information on the field required in your
- repo descriptor.
-
-- Edit the ``project/yml`` file and add a new line to the
- ``project.repositories`` variable with the name of the repo you are
- adding.
-
-An example of a ``project.yml`` file with two repositories is shown
-below:
-
-.. code-block:: console
-
- project.name: "my_project"
-
- project.repositories:
- - apache-Mynewt-core
- - Mynewt_arduino_zero
-
- # Use github's distribution mechanism for core ASF libraries.
- # This provides mirroring automatically for us.
- #
- repository.apache-Mynewt-core:
- type: github
- vers: 1-latest
- user: apache
- repo: mynewt-core
-
- # a special repo to hold hardware specific stuff for arduino zero
- repository.Mynewt_arduino_zero:
- type: github
- vers: 1-latest
- user: runtimeco
- repo: Mynewt_arduino_zero
-
-What Version of the Repo to use
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Mynewt repos are version-ed artifacts. They are stored in source control
-systems like github. The repo descriptor in your ``project.yml`` file
-must specify the version of the repo you will accept into your project.
-
-For now, we are at the beginnings of Mynewt. For testing and evaluation
-please use ``1-latest`` in the ``vers`` field in your repo descriptor.
-
-::
-
- vers:1-latest
-
-See `Create a Repo <create_repo>`__ for a description of the versioning
-system and all the possible ways to specify a version to use.
-
-Identifying a Repo
-~~~~~~~~~~~~~~~~~~
-
-A repo contains Mynewt packages organized in a specific way and stored
-in one of the supported code storage methods described above. In other
-words, it is a Mynewt project with an additional file ``repository.yml``
-which describes the repo for use by ``newt`` (and humans browsing them).
-It contains a mapping of version numbers to the actual github branches
-containing the source code.
-
-Note that the ``repository.yml`` file lives only in the master branch of
-the git repository. ``Newt`` will always fetch this file from the master
-branch and then use that to determine the actual branch required
-depending on the version specified in your ``project.yml`` file. Special
-care should be taken to ensure that this file exists only in the master
-branch.
-
-Here is the ``repository.yml`` file from the apache-Mynewt-core:
-
-.. code-block:: console
-
- repo.name: apache-mynewt-core
- repo.versions:
- "0.0.0": "master"
- "0.0.1": "master"
- "0.7.9": "mynewt_0_8_0_b2_tag"
- "0.8.0": "mynewt_0_8_0_tag"
- "0.9.0": "mynewt_0_9_0_tag"
- "0.9.9": "mynewt_1_0_0_b1_tag"
- "0.9.99": "mynewt_1_0_0_b2_tag"
- "0.9.999": "mynewt_1_0_0_rc1_tag"
- "1.0.0": "mynewt_1_0_0_tag"
-
- "0-latest": "1.0.0" # 1.0.0
- "0-dev": "0.0.0" # master
-
- "0.8-latest": "0.8.0"
- "0.9-latest": "0.9.0"
- "1.0-latest": "1.0.0" # 1.0.0
-
-It contains the following:
-
-- **repo.name** The external name that is used to include the library
- in your ``project.yml`` file. This is the name you in include in the
- ``project.repositories`` variable when adding this repository to your
- project.
-- **repo.versions** A description of what versions to give the user
- depending on the settings in their ``project.yml`` file.
-
-Repo Version
-~~~~~~~~~~~~
-
-The repo version number resolves to an actual git branch depending on
-the mapping specified in ``repository.yml`` for that repo. The version
-field argument in your ``project.yml`` file supports multiple formats
-for flexibility:
-
-.. code-block:: console
-
- <major_num>.<minor_num>.<revision_num>
-
-or
-
-.. code-block:: console
-
- <major_num>.<minor_num>-<stability string>
-
-or
-
-.. code-block:: console
-
- <major_num>-<stability string>
-
-The stability string can be one of 3 pre-defined stability values.
-
-1. stable -- A stable release version of the repository
-2. dev -- A development version from the repository
-3. latest -- The latest from the repository
-
-In your ``project.yml`` file you can specify different combinations of
-the version number and stability value. For example:
-
-- ``1-latest`` -- The latest version with major number 1
-- ``1.2-stable`` -- The latest stable version with major and minor
- number 1.2
-- ``1.2-dev`` -- The development version from 1.2
-- ``1.1.1`` -- a specific version 1.1.1
-
-You cannot specify a stability string with a fully numbered version,
-e.g.
-
-.. code-block:: console
-
- 1.2.8-stable
-
-Repo Versions Available
-~~~~~~~~~~~~~~~~~~~~~~~
-
-A ``repository.yml`` file contains information to match a version
-request into a git branch to fetch for your project.
-
-It's up to the repository maintainer to map these to branches of the
-repository. For example, let's say in a fictitious repository the
-following are defined.
-
-.. code-block:: console
-
- repo.versions:
- "0.8.0": "xxx_branch_0_8_0"
- "1.0.0": "xxx_branch_1_0_0"
- "1.0.2": "xxx_branch_1_0_2"
- "1.1.1": "xxx_branch_1_1_0"
- "1.1.2": "xxx_branch_1_1_2"
- "1.2.0": "xxx_branch_1_2_0"
- "1.2.1": "xxx_branch_1_2_1"
- "1.2-dev": "1.2.1"
- "1-dev": "1.2-dev"
- "1.2-stable": "1.2.0"
- "0-latest": "0.8.0"
- "1-latest": "1-dev"
- ....
-
-When the ``project.yml`` file asks for ``1.2-stable`` it is resolved to
-version ``1.2.0`` (perhaps ``1.2.1`` is not stable yet), which in turn
-resolves to a specific branch ``xxx_branch_1_2_0``. This is the branch
-that ``newt`` fetches into your project.
-
-**Note:** Make sure a repo version exists in the ``repository.yml`` file
-of a repo you wish to add. Otherwise Newt will not be able to resolve
-the version and will fail to fetch the repo into your project.
-
-How to find out what Repos are available for Mynewt components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Currently, there is no ``newt`` command to locate/search Mynewt package
-repositories. However, since the ``newt`` tool supports only github,
-searching github by keyword is a satisfactory option until a search tool
-is created.
-
-When searching github, recall that a Mynewt repository must have a
-``repository.yml`` file in its root directory. If you don't see that
-file, it's not a Mynewt repository and can't be included in your project
-via the newt tool.
-
-Once you find a repository, the github URL and ``repository.yml`` file
-should give you all the information to add it to your ``project.yml``
-file.
-
-
diff --git a/docs/os/tutorials/repo/create_repo.rst b/docs/os/tutorials/repo/create_repo.rst
deleted file mode 100644
index 9658fa9ef..000000000
--- a/docs/os/tutorials/repo/create_repo.rst
+++ /dev/null
@@ -1,186 +0,0 @@
-Create a Repo out of a Project
-------------------------------
-
-In order to create a repository out of a project, all you need to do is
-create a ``repository.yml`` file, and check it into the master branch of
-your project.
-
-**NOTE:** Currently only github source control service is supported by
-our package management system, but support for plain git will be added
-soon.
-
-The repository.yml defines all versions of the repository and the
-corresponding source control tags that these versions correspond to. As
-an example, if the repository.yml file has the following content, it
-means there is one version of the apache-mynewt-core operating system
-available, which is ``0.0.0`` (implying we haven't released yet!). Such
-a version number corresponds to the "develop" branch in this repository.
-``0-latest`` would also resolved to this same ``0.0.0`` version. The
-next section explains the versioning system a bit more.
-
-::
-
- $ more repository.yml
- repo.name: apache-mynewt-core
- repo.versions:
- "0.0.0": "develop"
- "0-latest": "0.0.0"
-
-Where should the repository.yml file be?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``repository.yml`` file lives only in the master branch of the git
-repository. ``Newt`` will always fetch this file from the master branch
-and then use that to resolve the actual branch required depending on the
-version specified in the project. **Special care should be taken to
-ensure that this file exists only in the master branch.**
-
-Here is the ``repository.yml`` file from a certain snapshot of
-apache-Mynewt-core:
-
-::
-
- repo.name: apache-mynewt-core
- repo.versions:
- "0.7.9": "Mynewt_0_8_0_b2_tag"
- "0-latest": "0.7.9"
- "0.8-latest": "0.7.9"
-
-It contains the following:
-
-- **repo.name** The external name that is used to include the library
- in your ``project.yml`` file. This is the name you include in the
- ``project.repositories`` variable when adding this repository to your
- project.
-- **repo.versions** A description of what versions to give the user
- depending on the settings in their ``project.yml`` file. See below
- for a thorough description on versioning. Its a flexible mapping
- between version numbers and git branches.
-
-Repo Version Specification
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The version field argument for a repo has the following format:
-
-.. code-block:: console
-
- <major_num>.<minor_num>.<revision_num>
-
-or
-
-.. code-block:: console
-
- <major_num>.<minor_num>-<stability string>
-
-or
-
-.. code-block:: console
-
- <major_num>-<stability string>
-
-The stability string can be one of 3 pre-defined stability values.
-
-1. stable -- A stable release version of the repository
-2. dev -- A development version from the repository
-3. latest -- The latest from the repository
-
-In your ``project.yml`` file you can specify different combinations of
-the version number and stability value. For example:
-
-- ``1-latest`` -- The latest version with major number 1
-- ``1.2-stable`` -- The latest stable version with major and minor
- number 1.2
-- ``1.2-dev`` -- The development version from 1.2
-- ``1.1.1`` -- a specific version 1.1.1
-
-You **cannot** specify a stability string with a fully numbered version,
-e.g.
-
-.. code-block:: console
-
- 1.2.8-stable
-
-Repo Version Resolution
-~~~~~~~~~~~~~~~~~~~~~~~
-
-A ``repository.yml`` file contains information to match this version
-request into a git branch to fetch for your project.
-
-It's up to you as the repository maintainer to map these to actual
-github branches of the repository. For example, let's say in a
-fictitious repository the following are defined.
-
-.. code-block:: console
-
- repo.versions:
- "0.8.0": "xxx_branch_0_8_0"
- "1.0.0": "xxx_branch_1_0_0"
- "1.0.2": "xxx_branch_1_0_2"
- "1.1.1": "xxx_branch_1_1_0"
- "1.1.2": "xxx_branch_1_1_2"
- "1.2.0": "xxx_branch_1_2_0"
- "1.2.1": "xxx_branch_1_2_1"
- "1.2-dev": "1.2.1"
- "1-dev": "1.2-dev"
- "1.2-stable": "1.2.0"
- "0-latest": "0.8.0"
- "1-latest": "1-dev"
- ....
-
-When the ``project.yml`` file asks for ``1.2-stable`` it will be
-resolved to version ``1.2.0`` which in turn will resolve to a specific
-branch ``xxx_branch_1_2_0``. This is the branch that ``newt`` will fetch
-into the project with that ``project.yml`` file.
-
-Dependencies on other repos
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Repositories can also have dependencies on other repositories. These
-dependencies should be listed out on a per-tag basis. So, for example,
-if apache-mynewt-core were to depend on sterlys-little-repo, you might
-have the following directives in the repository.yml:
-
-::
-
- develop.repositories:
- sterlys-little-repo:
- type: github
- vers: 0.8-latest
- user: sterlinghughes
- repo: sterlys-little-repo
-
-This would tell Newt that for anything that resolves to the develop
-branch, this repository requires the sterlys-little-repo repository.
-
-Dependencies are resolved circularly by the newt tool, and every
-dependent repository is placed as a sibling in the repos directory.
-Currently, if two repositories have the same name, they will conflict
-and bad things will happen.
-
-When a repository is installed to the repos/ directory, the current
-version of that repository is written to the "project.state" file. The
-project state file contains the currently installed version of any given
-repository. This way, the current set of repositories can be recreated
-from the project.state file reliably, whereas the project.yml file can
-have higher level directives (i.e. include 0.8-stable.)
-
-Resolving dependencies
-~~~~~~~~~~~~~~~~~~~~~~
-
-At the moment, all dependencies must match, otherwise newt will provide
-an error. As an example, if you have a set of dependencies such that:
-
-::
-
- apache-mynewt-core depends on sterlys-little-repo 0.6-stable
- apache-mynewt-core depends on sterlys-big-repo 0.5.1
- sterlys-big-repo-0.5.1 depends on sterlys-little-repo 0.6.2
-
-where 0.6-stable is 0.6.3, the newt tool will try and resolve the
-dependency to sterlys-little-repo. It will notice that there are two
-conflicting versions of the same repository, and not perform
-installation.
-
-In the future Newt will be smarter about loading in all dependencies,
-and then looking to satisfy those dependencies to the best match of all
-potential options.
diff --git a/docs/os/tutorials/repo/private_repo.rst b/docs/os/tutorials/repo/private_repo.rst
deleted file mode 100644
index 48f82c750..000000000
--- a/docs/os/tutorials/repo/private_repo.rst
+++ /dev/null
@@ -1,33 +0,0 @@
-Accessing a private repository
-------------------------------
-
-To access a private repository, newt needs to be configured with one of
-the following:
-
-- Access token for the repository
-- Basic auth login and password for the user
-
-**NOTE:** To create a github access token, see
-https://help.github.com/articles/creating-an-access-token-for-command-line-use/
-
-There are two ways to specify this information, as shown below. In these
-examples, both a token and a login/password are specified, but you only
-need to specify one of these.
-
-1. project.yml (probably world-readable and therefore not secure):
-
-``hl_lines="6 7 8" repository.my-private-repo: type: github vers: 0-dev user: owner-of-repo repo: repo-name token: '8ab6433f8971b05c2a9c3341533e8ddb754e404e' login: githublogin password: githubpassword``
-
-2. $HOME/.newt/repos.yml
-
-``hl_lines="2 3 4" repository.my-private-repo: token: '8ab6433f8971b05c2a9c3341533e8ddb754e404e' login: githublogin password: githubpassword``
-
-If both a token and a login+password are specified, newt uses the token.
-If both the project.yml file and the private repos.yml file specify
-security credentials, newt uses the project.yml settings.
-
-**NOTE:** When newt downloads the actual repo content, as opposed to
-just the repository.yml file, it does not use the same mechanism.
-Instead, it invokes the git command line tool. This is an annoyance
-because the user cannot use the same access token for all git
-operations. This is something that will be fixed in the future.
diff --git a/docs/os/tutorials/repo/upgrade_repo.rst b/docs/os/tutorials/repo/upgrade_repo.rst
deleted file mode 100644
index 8da25881d..000000000
--- a/docs/os/tutorials/repo/upgrade_repo.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-Upgrade a repo
---------------
-
-In order to upgrade a previously installed repository, the "newt
-upgrade" command should be issued:
-
-::
-
- $ newt upgrade
-
-Newt upgrade will look at the current desired version in
-``project.yml``, and compare it to the version in ``project.state``. If
-these two differ, it will upgrade the dependency. Upgrade works not just
-for the dependency in ``project.yml``, but for all the sub-dependencies
-that they might have.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services