I have a note in a reStructuredText formatted text that will be placed between a point of a list, and its sublist. The problem is that the note include the sublist.
Here is an extract of the file:
3. Select build parameters on the `CI
<https://website.com/CI>`_ and run it on your
remote branch.
.. note::
The text of the note.
a. If the failure is not related to your changes, say so in the pull request
comments.
b. Then, make the appropriate fixes.
4. Wait for comments or approval. If modifications are requested by the
comments, consider implementing them.
When I compile it, a. and b. are included into the note. But I don't want that. Is there a way to force the note to end after The text of the note. ?
Whitespace has meaning in reStructuredText. You need to indent appropriately. Also for nested lists, a blank line is necessary when the nesting level changes.
3. Select build parameters on the `CI <https://website.com/CI>`_ and run it on your remote branch.
.. note::
The text of the note.
a. If the failure is not related to your changes, say so in the pull request comments.
b. Then, make the appropriate fixes.
4. Wait for comments or approval. If modifications are requested by the comments, consider implementing them.
Note that I indent 4 spaces and do not use line breaks within a sentence. Docs are not code, and do not need to be wrapped.
The problem could be an indentation problem.
If the note is related to the 3. point, this answer seems to be good.
Else, if the note is related to a sublist element, you need to indent one more time the note.
3. Select build parameters on the `CI
<https://website.com/CI>`_ and run it on your
remote branch.
.. note::
The text of the note.
a. If the failure is not related to your changes, say so in the pull request
comments.
b. Then, make the appropriate fixes.
4. Wait for comments or approval. If modifications are requested by the
comments, consider implementing them.
This answer is wrong. See the comments for why. See Steve Piercy's answer for a correct one.
Probably something like the following:
3. Select build parameters on the `CI
<https://website.com/CI>`_ and run it on your
remote branch.
.. note::
The text of the note.
..
a. If the failure is not related to your changes, say so in the pull request
comments.
b. Then, make the appropriate fixes.
4. Wait for comments or approval. If modifications are requested by the
comments, consider implementing them.
Related
I am trying build an api which conforms to the json:api spec.
My api has three resources /task, /item and /result. A task has the fields name, description and state. A item has the fields itemName. A count is kept server-site for the item and the count is returned when a user retrieves the item with a GET request. The count is incremented server-side when the item is updated. There is a one-to-many relationship between task and item. In a sense an item is appended to a task. When the tasks state changes a script runs server-side to do some processing on the associated items. Once the script finishes the output is available in the result resource.
Per the spec, I am using the POST verb to create a task and the PATCH to update a task. I just want one endpoint which handles both the create /update (appending) of an item. But, I'm not sure which verb to use? Can I use PATCH to update the item but also create an item if it doesn't exist?
I also thought that perhaps I should be using the PUT verb. But, my understanding here is that this verb is used to simply replace a resource rather than update it. I don't think this is right for my user-case as an items count is incremented when updated, so replacing it is not what I want todo. But, the count is handled server-side so a user doesn't have the option of "replacing" the count anyway.
my understanding here is that this verb is used to simply replace a resource rather than update it.
This is a common understanding - wrong, but common.
The IANA registry documents the authoritative reference for the semantics of http methods. Most of the common ones are defined by RFC 7231; PATCH is defined by RFC 5789.
PUT is an appropriate choice when the message body is a complete representation of what you want the resource to be. It may be easier to think about "saving a file"; PUT describes what the client expects the document to look like when it has been saved.
It's appropriate to use PUT for either updating a document or creating one, provided that the client knows the identifier for the document (just in the same way that we can use save to create a file, or replace a file, but we need to know the file name).
If you read the text of the specification, you'll see that - while the semantics of the request are to save the new representation "as-is", the server isn't required to do that -- the server, after all, is in control of its own documents -- so there is room to cover read only fields, or fields that should be updated by the server only. You need to have a little bit of care with the response headers to avoid implying that you saved the representation as is, but other than that you should be fine.
How to avoid duplicated Cucumber steps while multiple team members working on different feature files in parallel?
Sometimes we find some similar steps with different context but are 90%-100% the same. The problem occurs when the tests are complex and need to write new steps for new feature that we didn't have before.
Any tips good tips that could help solving this issue?
Are there good tools that can manage and search steps to avoid duplicated statements?
Thanks,
Everyone writes scenarios in a different way.
One way you could start to avoid duplication is to document your steps and what they do, so that you and your team can look back on them to see if there is an existing step that they can use.
For steps where the functionality is almost the same, you could merge the step definitions: Given I have logged in vs When I log in - Cucumber Expression: "I( have) log(ged) in", Regex: /I(?:| have) log(?:|ged) in/ as an example.
For your example, we would need to know what you're trying to achieve in your step definition. For instance, you could be filling out a form where you have to select an option in a drop down dependant on the user that is logged in:
Psuedo-Code:
// Some stuff here to get to the dropdown
if(user.name === "Bob Ross"){
form.dropdown.select.option(2);
} else if (user.name === "Ellen Ripley"){
form.dropdown.select.option(3);
} else {
form.dropdown.select.option(1);
}
// Some other stuff here to complete this step
Basically, it depends on what you're attempting to do with your semi-duplicate steps.
Can you check what journey you are completing (with a previously ran step and a variable, a Url, a user that is logged in etc) and do something differently? Perhaps write a helper function for it and keep the step definition as just a block of ifs to choose the right one.
Can you merge steps that hold the same functionality?
If you can do either of these, then you should be good to go.
I'm trying to automate some deployments and I need to comment out some configuration, which essentially comprises of a full block. Is there a way to comment a particular block of code/configuration via ansible playbook?
Commenting a whole block will be very hard. I can't think of a way to do this without a custom written module.
If it is an option, you can remove a block with the blockinfile module, which has an state: absent option. Unfortunately it does not have regex option to identify a block, which would be required to identify your commented/uncommented block. If it helps, the blockinfile module can create a backup with the original content.
The docs on the galaxy page are a bit broken. See the github page for better formatting.
Say I have a table for machines, and one of the columns is called status. This can be either active, inactive, or discarded. A discarded machine is no longer useful and it only used for transaction purposes.
Assume now I want to discard a machine. Since this is an entry update, RESTfully, this would be a PUT request to /machines/:id. However, since this is a very special kind of an update, there could be other operations that would occur as well (for instance, remove any assigned users and what not).
So should this be more like a POST to /machines/:id/discard?
From a strict REST perspective, have you considered implementing a PATCH? In this manner, you can have it update just that status field and then also tie it in to updating everything else that is necessary?
References:
https://www.mnot.net/blog/2012/09/05/patch
http://jasonsirota.com/rest-partial-updates-use-post-put-or-patch
I think the most generic way would be to POST a Machine object with { status: 'discarded' } to /machines/:id/.
Personally, I'd prefer the /machines/:id/discard approach, though. It might not be exactly in accordance with the spec, but it's more clear and easier to filter. For example, some users might be allowed to update a machine but not "archive" it.
Personally I think post should be used when the resource Id is either unknown or not relevant to the update being made.
This would make put the method I would use especially since you have other status types that will also need to be updated
path
/machines/id
Message body
{"status":"discarded"}
I am struggling (in some sense) to determine which HTTP method is more appropriate for rebooting a remote resource: GET or PUT?
On one hand, it seems more semantic to call http://tools.serviceprovider.net/canopies/d34db33fc4f3?reboot=true because one might want to GET a representation of a freshly rebooted canopy.
On the other hand, a reboot is not 'safe' (nor is it necessarily idempotent, but then a canopy or modem is not just a row in a database) so it might seem more semantic to PUT the canopy into a state of rebooting, then have the server return a 202 to indicate that the reboot was initiated and is processing.
I have been reading up on HTTP/1.1, REST, HATEOAS, and other related concepts over the last week, so I am still putting the pieces together. Could a more seasoned developer please weigh in and confirm or dispel my hunch?
A GET doesn't seem appropriate because a GET is expected, like you said, to be "safe". i.e. no action other than retrieval.
A PUT doesn't seem appropriate because a PUT is expected to be idempotent. i.e. multiple identical operations cause same side-effects as as a single operation. Moreover, a PUT is usually used to replace the content at the request URI with the request body.
A POST appears most appropriate here. Because:
A POST need not be safe
A POST need not be idempotent
It also appears meaningful in that you are POSTing a request for a reboot (much like submitting a form, which also happens via POST), which can then be processed, possibly leading to a new URI containing reboot logs/results returned along with a 303 See Other status code.
Interestingly, Tim Bray wrote a blog post on this exact topic (which method to use to tell a resource representing a virtual machine to reboot itself), in which he also argued for POST. At the bottom of that post there are links to follow-ups on that topic, including one from none other than Roy Fielding himself, who concurs.
Rest is definitely not HTTP. But HTTP definitely does not have only four (or eight) methods. Any method is technically valid (even if as an extension method) and any method is RESTful when it is self describing — such as ‘LOCK’, ‘REBOOT’, ‘DELETE’, etc. Something like ‘MUSHROOM’, while valid as an HTTP extension, has no clear meaning or easily anticipated behavior, thus it would not be RESTful.
Fielding has stated that “The REST style doesn’t suggest that limiting the set of methods is a desirable goal. [..] In particular, REST encourages the creation of new methods for obscure operations” and that “it is more efficient in a true REST-based architecture for there to be a hundred different methods with distinct (non-duplicating), universal semantics.”
Sources:
http://xent.com/pipermail/fork/2001-August/003191.html
http://tech.groups.yahoo.com/group/rest-discuss/message/4732
With this all in mind I am going to be 'self descriptive' and use the REBOOT method.
Yes, you could effectively create a new command, REBOOT, using POST. But there is a perfectly idempotent way to do reboots using PUT.
Have a last_reboot field that contains the time at which the server was last rebooted. Make a PUT to that field with the current time cause a reboot if the incoming time is newer than the current time. If an intermediate server resends the PUT, no problem -- it has the same value as the first command, so it's a no-op.
You might want to get the current time from the server you're rebooting, unless you know that everyone is reasonably time-synced.
Or you could just use a times_rebooted count, eliminating the need for a clock. A PUT times_rebooted: 4 request will cause a reboot if times_rebooted is currently 3, but not if it's 4 or 5. If the current value is 2 and you PUT a 4, that's an error.
The only advantage to using time, if you have a clock, is that sometimes you care about when it happened. You could of course have BOTH a times_rebooted and a last_reboot_time, letting times_rebooted be the trigger.