Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 119 lines (74 sloc) 5.235 kb
b44768c @yrashk Added initial CONTRIBUTING.md
yrashk authored
1 CONTRIBUTING
2 ============
3
4 How can I suggest a new package?
5 --------------------------------
6
7 Just [open an issue](https://github.com/agner/agner/issues) with your suggestion.
8
9 How can I create a new package?
10 -------------------------------
11
12 You can create a spec repository by forking and renaming [template package repo](https://github.com/agner/agner.template)
218e50a @yrashk Added reference to 'agner create' command in CONTRIBUTING.md
yrashk authored
13 and later on submitting it for inclusion by [opening an issue](https://github.com/agner/agner/issues). One of the most
14 convenient ways to do this is to use `agner create` command. Please note
15 that if you don't have owner permissions at `agner` GitHub account,
16 please supply your account name using `--github-account NAME` option.
17 The last step (opening an issue to include it into the central repository) is only necessary if you want this package to be published on a "central" index.
b44768c @yrashk Added initial CONTRIBUTING.md
yrashk authored
18 If you want to keep it semi-private, you can just use it from your own index.
19
150b9c7 @yrashk Help spreading the word section in CONTRIBUTING.md
yrashk authored
20 Help spreading the word!
21 ------------------------
22
23 Success of Agner project relies on you, Erlang package authors && maintainers. If you can mention that
24 Agner can be used to fetch, build or install your package, we'll be getting more attention to our central index
25 of packages, which is beneficial for the entire community. Please consider including this information into your
26 READMEs and/or web pages.
27
5010b7a @yrashk Added a little bit more information on tag shuffling to CONTRIBUTING.md
yrashk authored
28 Mastering specification
29 -----------------------
30
b2fcaa4 @yrashk Fixed broken link in README.md
yrashk authored
31 First of all, please take some time to read through [README](README.md) to make sure you understand all the concepts,
5010b7a @yrashk Added a little bit more information on tag shuffling to CONTRIBUTING.md
yrashk authored
32 especially how versioning is done.
33
34 Also, even though in Git world you can be crucified for deleting remote tags (`release` versions in our lingo), in Agner,
35 even not encouraged, this type of action is tolerable if you need to change the specification of an already published release.
36 `.agner` repos are intended for quick fresh cloning so shuffling tags in them is not that critical. If you do anticiapte anticipate that somebody has a fork of your `.agner` repo, though, please communicate your tag changes to them, just in case. One of
37 the ways might be adding some README or NOTES file into your `.agner` repo.
38
b44768c @yrashk Added initial CONTRIBUTING.md
yrashk authored
39 Before commiting your agner.config, please make sure you ran `agner verify` on it so it passes at least
5010b7a @yrashk Added a little bit more information on tag shuffling to CONTRIBUTING.md
yrashk authored
40 some validity checks.
41
90339e4 @yrashk Fixing markdown syntax in CONTRIBUTING.md
yrashk authored
42 ### Build command
d72210f @yrashk Added a little bit more information on how to define custom build & i…
yrashk authored
43
44 If your target repository can't be built by simply invoking `rebar get-deps && rebar compile` then you need to supply
45 a `build_command` property, for example:
46
47 {build_command, "make"}.
48
c16fa32 @yrashk build_command and rebar_compatible are no longer exclusive, build_com…
yrashk authored
49 Alternatively, you can also use it to finalize build process after rebar get-deps & compile for rebar compatible projects.
50
d72210f @yrashk Added a little bit more information on how to define custom build & i…
yrashk authored
51 The build command will be invoked in checked out directory containing target repository.
52
90339e4 @yrashk Fixing markdown syntax in CONTRIBUTING.md
yrashk authored
53 ### Install command
d72210f @yrashk Added a little bit more information on how to define custom build & i…
yrashk authored
54
a785026 @yrashk Fixed install_command documentation
yrashk authored
55 If your target package can't be installed by simply copying otp directories then you need to supply
56 an `install_command` property, for example:
d72210f @yrashk Added a little bit more information on how to define custom build & i…
yrashk authored
57
58 {install_command, "make install"}.
59
60 The install command will be invoked in checked out directory containing target repository.
61
62
90339e4 @yrashk Fixing markdown syntax in CONTRIBUTING.md
yrashk authored
63 ### Environment Variables
d72210f @yrashk Added a little bit more information on how to define custom build & i…
yrashk authored
64
65 Here's the current list of environmentvariables that will be available to build & install commands:
66
c4926b2 @yrashk Fixed a wrong word in CONTRIBUTING.md
yrashk authored
67 * AGNER -- Absolute path to the agner script file
7b2433c @yrashk Now every installed package is isolated in its own directory and can …
yrashk authored
68 * AGNER_PREFIX -- Root agner's directory (defaults to `/usr/local/agner`)
ed2e895 @yrashk Added minimal documentation on AGNER_PACKAGE_REPO variable
yrashk authored
69 * AGNER_PACKAGE_REPO -- Path to checked out .agner repo
85fe0c8 @yrashk Add AGNER_PACKAGE_NAME and AGNER_PACKAGE_VERSION environment variable…
yrashk authored
70 * AGNER_PACKAGE_NAME -- Name of the package
71 * AGNER_PACKAGE_VERSION -- Version of the package
7b2433c @yrashk Now every installed package is isolated in its own directory and can …
yrashk authored
72 * AGNER_INSTALL_PREFIX -- A place where install procedure should consider putting installable files to. Right now it equates to
73 `AGNER_PREFIX/agner/packages/<package_name>-<package_version>`
d72210f @yrashk Added a little bit more information on how to define custom build & i…
yrashk authored
74
75 More variables to come later.
1b43447 @yrashk Added documentation on hidden branches & tags in CONTRIBUTING.md
yrashk authored
76
b84bf97 @yrashk Very minor fix in CONTRIBUTING.md
yrashk authored
77 ### Private Branches & Tags
1b43447 @yrashk Added documentation on hidden branches & tags in CONTRIBUTING.md
yrashk authored
78
79 If you want to have either branches or tags that shouldn't be exposed to the end user as versions when they inquire using
80 `agner versions`, simply prepend your branch or tag name with `%` (comment) symbol and it will be hidden from the general public.
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
81 It will still be possible to use such versions explicitly, though (for example, `agner spec erlv8 -v @%test` for a branch called `%test`)
82
83 ## Tips & Tricks
84
85 ### Rewriting multiple versions
86
87 Ever found yourself in a situation when you made a typo across multiple versions of the specification? I know I did, multiple
88 times. So here's a quick-n-dirty solution for this.
89
90 Let's assume you have a branch named `release` (@release flavour) and some release versions that you want to rewrite; and you need to change misspelled `nae` property to `name`.
91
92 What you can do is:
93
94 1. Create new `release2` branch
95
1112906 @yrashk Minor formatting update in CONTRIBUTING.md
yrashk authored
96 git checkout -b release2
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
97
98 2. Do the actual replacement
99
1112906 @yrashk Minor formatting update in CONTRIBUTING.md
yrashk authored
100 git tag -l | sort | xargs -I {} sh -c 'git cherry-pick -n {} && cat agner.config | sed s/nae/name/g > agner.new && mv agner.new agner.config && git add agner.config && git commit -C {} && git tag -d {} && git tag {}'
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
101
102 3. Remove remote `release branch`
103
1112906 @yrashk Minor formatting update in CONTRIBUTING.md
yrashk authored
104 git push origin :release
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
105
106 4. Push `remote2` as `remote`
107
1112906 @yrashk Minor formatting update in CONTRIBUTING.md
yrashk authored
108 git push origin release2:release
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
109
110 5. Remove remote tags:
111
1112906 @yrashk Minor formatting update in CONTRIBUTING.md
yrashk authored
112 git tag -l | xargs -I {} git push origin :{}
b9fefa5 @yrashk Added a tip for contributors on how to make changes across multiple v…
yrashk authored
113
114 6. Push tags:
115
3b7fb9d @yrashk Added a little note to CONTRIBUTING.md section on how to rewrite mult…
yrashk authored
116 git push origin --tags
117
218e50a @yrashk Added reference to 'agner create' command in CONTRIBUTING.md
yrashk authored
118 P.S. If you want to stick to proper release version tags only (for example, if you use hidden % tags), you might want to use `agner versions PACKAGE --no-flavours` command instead of `git tag -l`
Something went wrong with that request. Please try again.